Explaining what and why.
WHAT CODE SHOULD EXPLAIN ITSELF
What it does, through naming and structure.
WHAT COMMENTS SHOULD EXPLAIN
Why: the reasoning, the constraint, the decision.
WHY THAT DISTINCTION
What can be read from the code. Why cannot.
WHAT TO COMMENT
Non-obvious decisions Workarounds, with the reason Constraints from outside the code Anything surprising
WHAT NOT TO COMMENT
What the line plainly does.
WHY
Those comments become wrong when the code changes, and then mislead.
WHAT DOCUMENTATION COMMENTS PROVIDE
Descriptions attached to functions and types, extracted into reference documentation.
WHAT TO DOCUMENT IN THEM
What it does What each parameter means What is returned What errors may occur
WHAT ELSE A PROJECT NEEDS
A readme: what it is, how to set it up, how to run it, how to deploy it
Architecture notes, explaining structure and decisions
WHAT TO KEEP CURRENT
All of it.
WHY
Out-of-date documentation is worse than none, because it is trusted.
WHAT TO GENERATE
Reference documentation from the code.
