Code comments

In short: Comments are text in source code that the computer ignores. They explain the why, not the what.

In more detail: Good code largely explains itself through clear names. Comments add what cannot be seen in the code: reasons, assumptions, pitfalls, references.

In detail

• Single-line: // (Java, C, JS, C#, Go), # (Python, shell, YAML), -- (SQL, Lua).
• Multi-line: /* … */ (C family), """ … """ as a docstring in Python, <!-- … --> in HTML.
• Documentation comments: /** … */ (Javadoc) and Python docstrings generate documentation automatically.
• Bad: i++; // increases i by 1 only repeats the code.
• Good: // timeout 30s because the partner server answers slowly.
• TODO/FIXME: markers for open work, highlighted by editors.
• Commenting out: switching off code temporarily, but better delete it and rely on version control (git).

See also: README file, Constants