logoalt Hacker News

alexpotatotoday at 1:48 PM5 repliesview on HN

There is an old quote:

"Add comments to your code under the assumption that the next person to maintain it is a homicidal maniac who knows where you live"


Replies

TimTheTinkertoday at 2:55 PM

Right now the comments that upset me the most are LLM TMI-style comments that break encapsulation by talking about the behavior of specific current callers of a function right above the function definition.

I recently reacted angrily in a PR review comment after encountering one for the umpteenth time... that caught me off guard. I didn't know I was capable of that.

show 6 replies
SoftTalkertoday at 3:21 PM

Used to work with a guy who would frequently say "a comment is an apology" i.e. the comment is there because the code itself is not clear. That can be the case, but I generally find more comments better than fewer, especially if they relate the code to actual business or functional requirements and don't just restate what the code is doing.

Years ago I would often write comments first. I.e. start with describing the overall goals. Then break it down into routines and order of operations, all still in plain english. Once I was happy with that, I'd break up the comments with blocks of code. I guess this is sort of like "literate programming" though I was doing it long before I ever heard that term and I still have never read much about it. It's almost more like I was prompting myself towards the end goal. The downside of this approach is that the comments do end up more or less just explaining in english what the code is doing, so maybe aren't quite as useful to future maintainers.

show 3 replies
hansonkdtoday at 1:58 PM

The comments that drive the most homicidal behavior are outdated or inaccurate comments rather than no comments.

show 3 replies
dioniantoday at 3:46 PM

sounds like a recipe for over-commenting. The code should be self-documenting. Comments are for the places where there are dragons.