PSA: A senior dev told me my code comments were useless, here is what I changed

I used to write comments like "this function does X" which just repeated the code. He told me comments should explain why the code exists, not what it does. Anybody else get feedback like that and realize they were doing it wrong for years?

4 comments

4 Comments

harper9147d ago

Man, that hits close to home. Had a lead dev once tell me my comments were like "noise" after I spent an hour explaining a regex pattern. He said if the code needs a novel to explain, rewrite the code not the comment. So I started writing comments like "ugly hack because API v2 breaks on Tuesdays, fix when we migrate." Way more useful.

the_max6d ago

Real life works the same way, half the stuff we do is just dodging weird edge cases nobody planned for.

rowanhernandez6d ago

Yeah the "why not what" thing is one of those lessons that takes way too long to stick. I had a coworker who would write comments like "increment counter" above a single line that said counter++. Then he'd get mad when people asked what it did. Now I just write stuff like "this loop exists because the database returns duplicates on weekends" or "sleep here prevents the rate limiter from banning us" - stuff you'd never guess from reading the code alone. Your "ugly hack because API v2 breaks on Tuesdays" is exactly the kind of thing that saves someone six hours six months later at 2 AM.

sage_moore376d ago

Rowan nailed it with that weekend duplicates thing. The real gold in comments is capturing the "why" that's invisible in the code itself. Like I had this one function that sorted things alphabetically but first checked if the dataset had an odd number of items, and the comment just said "legacy database returns Friday afternoon data in reverse order." Nobody would ever guess that from reading the sorting logic. Those little context clues are what separate helpful comments from noise. Harper's lead dev had a point about rewriting bad code, but sometimes the weird edge cases are baked into the system design itself and you just gotta document the insanity.