Code comment guidelines

With any given piece of code, the most likely person to look at it next and struggle to understand it will be the developer.

Each code file should tell a story so that the developer understands what each part of the code does. All other information, such as prerequisites and instructions for running the code, should be in the associated READMEs.

Excessive code comments can make the code more difficult to follow. To mitigate this, try to write code that is as human-readable and self-explanatory as possible. However, don’t try to be too clever. If what your code is doing isn't obvious, include descriptive comments about non-obvious reasons for doing things.

Here are some examples:

• Ruby code example - Code that is human-readable and includes functional comments
• Go code example - Code that tells what it's doing (not so much how it's doing it), but is written in a human-readable fashion
• Rust code example - Very human-readable code