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

Sure, but the proportion of code that drives homicidal behavior is heavily weighted towards non-comments. You're a lot more likely to piss off whoever inherits your code with the code that actually does something being bad or a lack of documentation than with comments.

▲

jraph 3 hours ago | parent | next [-]

I'm quite fine with no comments but correctly named variables and functions. This can't become out of sync contrarily to "out of band" comments. I take this over commented code with poorly named stuff any day.

I've also seen a lot of comments that restate what the code already says and that's just noise, more work to keep in sync, an additional thing that can fail, and more cognitive load because you have to read twice the same thing (best case, if code and comment are still in sync). That's the result you risk when you think you must comment your code.

I appreciate the occasional comment that explains why something seems overly tricky or weird or not immediately intuitive. Once, I had left such a comment that saved myself years later from making a mistake. Of course, this should be kept at a minimal level. It leads to me liking clear code with few comments the most. (Some guidelines, even if it's not perfect, to limit complexity and spaghetti code help a lot).

Function, class, module documentation is also useful so you don't have to read the whole thing and you know what it's intended to provide (which is slightly different than simply what it provides, and this differences is important).

▲

saghm 24 minutes ago | parent | next [-]

Yep, I think I agree with pretty much all of this. There are a lot of cases where clearer naming can avoid needing comments, but there are also some cases where the code itself won't be clear enough. My personal stance is that in a world where nobody is immune from accidentally making a mistake in logic and writing a bug, comments that clarify the intent of code that might otherwise look strange are valuable for future readers of the code (whether human or LLM); at worst, they can potentially help someone avoid wasting time going down a rabbit hole because Chesterton's fence didn't have a signpost on it, and at best they actually expose gaps in what's handled when someone is able to notice a discrepancy between what's documented and what's actually happening.

Clear code takes precedence over commented code if either of them could be used to solve the problem of communicating what's going on; comments are still useful in the cases where clear code isn't always enough. Of course, being able to discern whether there's a way to make the code cleaner to avoid needing a comment is an art rather than a science, and it's a skill that I think few people excel at (and judging by how so much LLM-generated code is littered with inane comments, one that's also pretty rare in agents)

▲

AnimalMuppet 3 hours ago | parent | prev [-]

I worked with this guy. He'd write the code, and comment where needed, and then he would ask "How can I make this comment unnecessary?" The answer was usually to rename something, so that what he was doing was obvious.

	▲	jraph 3 hours ago \| parent [-]
		Nice, I love this. That's pretty satisfying.

▲

mekoka 3 hours ago | parent | prev [-]

Ignorance will always be a better starting point for discovery than wrong assumptions. If you leave comments, they must reflect what the code is actually doing. If during edit it's no longer the case, at least mark them as stale. The next best thing is indeed to remove them.

▲

minraws 4 hours ago | parent | prev | next [-]

Both can be true at the same time, we can be equal opportunity murderers who treat lazy verbosity and hippester terse code.

▲

gowld 4 hours ago | parent | prev [-]

Put your home address in the comments. Problem solved.

	▲	sejje 3 hours ago \| parent [-]
		I moved after I wrote the comment. It's hard to keep everything up to date.