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 coder!

Each code files should tell the user a story, so the user 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 you should strive to write code that is as human readable and self-documenting as possible. But don’t try to be too clever. If what your code is doing isn’t obvious, you should include descriptive comments about non-obvious reasons for doing things.

Here are some examples:

• Ruby code example with that is human readable and has functional comments
• Go code example that tells what its doing, not so much how its doing it, but is written in a human readable fashion.
• Rust code example with very human readable code