Explaining code.
WHAT COMMENTS SHOULD EXPLAIN
Why, not what.
WHY NOT WHAT
The code already says what it does.
A comment restating it adds nothing and goes stale.
WHAT DESERVES A COMMENT
A non-obvious decision A workaround and its reason An assumption Something surprising
WHAT TO DO INSTEAD OF COMMENTING CONFUSING CODE
Rewrite the code.
DOCSTRINGS
Text at the start of a function or module describing its purpose.
Available to tools and to anyone reading.
WHAT A GOOD ONE STATES
What it does What it expects What it returns What it raises, if anything
WHAT TO DOCUMENT AT PROJECT LEVEL
What the project does How to set it up How to run it Any configuration required
WHAT TO KEEP UPDATED
Comments, when code changes.
A wrong comment is worse than none.
WHAT TO AVOID
Commented-out code left in place.
Version control keeps history; delete it.
