Writing Good Code Comments

Comments exist to capture information that was in the writer's mind but cannot be expressed in the code itself. Code states what happens mechanically; comments supply intent, contracts, rationale, units, invariants, and the higher-level picture. Good comments make a system understandable to someone reading it for the first time and let abstractions hide complexity. The cost is small — typically a fraction of development time — and it pays back every time someone (including the original author, weeks later) needs to read or change the code.

The one rule that governs everything

Comment things that aren't obvious from the code. Before keeping any comment, ask: Could someone who has never seen this code reconstruct this comment just by reading the code next to it? If yes, the comment adds nothing — delete it or replace it with something that does add information. "Obvious" means obvious to a first-time reader, not to you.

This single test eliminates most bad comments and motivates most good ones.

Don't repeat the code

The most common worthless comment simply restates the line below it, at the same level of detail.

i = i + 1          # increment i              ← adds nothing
count = len(items) # get the number of items  ← adds nothing