comment-code

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

A close cousin is the comment that just recycles the words already in the name:

// Obtain a normalized resource name from the request.
String[] getNormalizedResourceName(Request req) { ... }

The only word here not already in the signature is "from." This tells the reader nothing they couldn't read off the declaration. The fix is to use different words than the name, words that explain the meaning the name only hints at: What is a normalized resource name? What are the elements of the returned array? When in doubt, the giveaway is one-comment-per-line at the same granularity as the code.

Comments work at a different level of detail than the code

A comment at the same level as the code repeats it. Useful comments go either lower (more precise) or higher (more abstract) than the code.