Commenting Code

Programs must be written for people to read.

Readability may be the most valuable trait a program can have, including correctness. Perfectly correct programs are vanishingly rare, and readable programs are far more likely to get bugfixes.

Most programming languages support comments - blocks of text which do not change program behavior.

When writing comments, the tension between readability and computability vanishes. Their sole purpose is to improve readability.

Comments should not change the program's behavior. When they do, they are no longer comments, just obfuscated code.

That said, it's just fine, maybe even wise, to write tools that extract and process comments from a codebase.

Commenting programs well requires the understanding that every line of code is a user interface. Good user interfaces are simple and self-explanatory, and so should be each line of code. If a line is unclear, clarify it instead of commenting it. Improving names helps, as does adding new ones.

Inline comments can indicate poor code, but they do have several important uses. They are the best way to point out potential issues, to explain why a given algorithm or implementation was chosen, and to document workarounds (make sure to include all relevant URLs).

Every abstraction in a program should have a comment explaining what it is and how to use it (if the language supports docstrings, use them for this purpose).

That standard can be enforced automatically, and with it your tools can help you understand abstractions quickly, by showing their documentation whenever and wherever you need it.