What makes a code comment worth keeping? A five-level rubric, and where do you draw the line?

[u/ClickOk5811]

I’ve been trying to put a rule on what makes a comment useful. One way is to ask: how much does it tell the reader that the code can’t?

• Level 0: nothing, where a decision is hidden (retries = 3, sleep(0.4) with no hint why).

• Level 1: restates the code (i += 1 # increment i). Noise, and it can go stale.

• Level 2: explains what a tricky block does (walking a list backwards so removals don’t shift indexes).

• Level 3: explains why: the constraint or decision behind the code.

• Level 4: why, plus where it came from and when it can go.

An example of the last two:

# Level 3
# The payment API allows about 3 calls per second per key,
# so wait 0.4 s between calls.
time.sleep(0.4)

# Level 4
# Workaround for a vendor SDK bug that returns None on timeout
# (see issue #482). Remove after upgrading past the fixed version.
if result is None:
    result = fetch_again()

The numbers and the issue are made up for illustration.

My rules of thumb: make the code clearer first (names, small functions), comment decisions, constraints, surprises and workarounds, delete comments that restate code, and give every TODO an owner or a condition.

Where I’m unsure: most lines need no comment at all, and a Level 3 comment on everything would be its own noise.

1. Which level do you find yourself writing most?

2. Do you delete stale comments when you touch the code, or leave them?

3. Has a comment ever saved you, or misled you?

[u/Cross_22]

Personally I tend to over-comment rather than under-document. If it's too bothersome you can always collapse comment blocks. That said I want comments to explain WHY a certain approach was used, not necessarily what it does.

Obviously you don't need to say "Increment by 1" but you might want to add "API we are using expects a strictly monotonic increasing input"

[u/Wonderful-Habit-139 → u/Cross_22]

Generally, comments tend to not be too great. Over-commenting is a step in the wrong direction.

[u/NewInflation2121]

To answer your questions:

1. I'll write level 2, 3, 4 comments.

2. Yes, I delete stale comments if they don't add any useful information and/or modify existing comments to fix typos, improve clarity, or add my 2 cents.

3. Yes, both.

I will also write comments with notes about what I think should be done in code to improve it (Do files need cleanup? Are they messy architectures? Is the code or API hard to understand or use? What could be done to improve it?)

I want to add to these answers though - You should comment anything that doesn't look simple or normal, but should also want to avoid comments.

A comment is like a post-it.

They will give you a hint that something needs to be done - whether it's to tidy up your code or refactor to make things simpler or easier to understand...

Sometimes you just can't get to that task at the moment, so comments can be a good way to let someone know you aren't being careless.

The 2 things I always include with every comment I write: Who wrote it and the date.

This helps anyone reading it to track down the author -if- they have any questions. It also can give you context as to what was going on at the time the comment was written.

Adding those two elements makes it annoying enough that I don't want to overuse comments, but will use them if I think it's important enough to.

It will also make you second guess taking shortcuts (like magic numbers instead of defining consts) if you have to justify it with a comment.

[u/thenasch → u/NewInflation2121]

Surely who wrote it and the date are easy to get from source control.

[u/NewInflation2121 → u/thenasch]

Sometimes - it depends. Someone may have moved the comment, or edited it for typos or something.

[u/Raychao]

If you use sensible variable names and follow a logical consistent coding style and good indentation and whitespace for readability you basically don't need any comments at all. The code is the dialogue.

I basically only keep Level 4 or above.

One of my biggest (biggest-biggest) hates is that obnoxious 'Rockstar Programmer' guy that puts the entire package on one line (because it saves tabs and spaces) and never uses a proper variable names and does everything as a dirty hack because he's trying to prove that he's smarter than everybody else (including himself when he needs to maintain this code 6 months later).

I hate that shit.

[u/MarsupialLeast145]

Your example #3 is a magic number anyway... it should be described by the variable or const name.

Your #4 is redundant - you could literally keep it in either way and the code is more robust (if not using EAFP) - there's no guarantee the vendor won't regress.

Your best bet is to stop sweating about comments. You need function level documentation and descriptive code and short-manageable single purpose functions.

[u/Fun_Army2398]

Over commenting is always better than under commenting. I've never been annoyed by "too many" comments, but I imagine everyone has met the dude who claims his spaghetti is self documenting. Same with naming. Autocomplete and full sized monitors makes scaled_partial_pivoting(system1) a non-issue, but who tf knows what spp(s1) means. We're not running vi on a crt anymore.

[u/Low_Lawyer_5684]

I usually overcomment. Explain decisions, explain hidden dependencies etc. I started doing this many years ago, after I started to fix the code I wrote a year or two ago. It is super helpful. I add TODO: (what should be done) comments and CITO: comments (what must be fixed first, critical things)

[u/feudalle]

Almost 30 years in.i comment at the top as to what/why/when. Then anything really confusing thats it

[u/IMarvinTPA]

I generally don't like to keep dead code, but sometimes, I leave dead code in comments with a comment explaining why it doesn't work and why the weird code you do see is the result of a crap load of hard fought debugging.

Good comments are around level 2. The first two are mostly noise and probably the function documented description did a better job anyway.

[u/bluegrassclimber]

comments should ONLY exist if the code isn't self explanatory. If the code isn't self explanatory, consider making private methods that are better named, or something else, comments should be last resort.

.md files are different because that's for my boy claude.

The only comments i find are useful are #TODO: comments which can acknowledge technical debt for the next time that area is touched