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"

▲

TimTheTinker 3 hours ago | parent | next [-]

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.

▲

fphilipe 2 hours ago | parent | next [-]

This is what has been frustrating me most lately. Even though I have a rule in my global CLAUDE.md that says:

> Only write comments to explain the why when it is not obvious from the code (rationale, gotchas, constraints). Do not comment on the what — well-named code already says it. Do not comment on how a framework works.

It still keeps adding these bad comments. When I then ask it to review the comments based on my preferences it then deletes most of them or improves them.

Today I asked Claude why it disrespects my preference and it said that the surrounding code was like that and it followed that style. It suggested I add this line to my global CLAUDE.md file:

> The comment rule above beats the style of the surrounding code: neighboring files with what-style comments are not license to write more of them, and comments carried along when porting or copying code must be re-judged against the rule, not kept for consistency.

Let's see if that improves things.

▲

mnicky 2 hours ago | parent | next [-]

In Claude Code there are also "output styles" that are more deeply embedded - into a system prompt - and agent is also periodically reminded of them during the session: https://code.claude.com/docs/en/output-styles

Maybe these would work better for such cases.

▲

sheept 2 hours ago | parent | prev [-]

My hypothesis is that Claude is inclined to write so many comments as a way of doing additional thinking

	▲	disgruntledphd2 an hour ago \| parent [-]
		Yeah, it's short form memory or something. Like writing a todo list.

▲

j_bum 2 hours ago | parent | prev | next [-]

This drives me nuts as well. I hate also hate when LLMs use plan-document references in comments/doc strings too. “Landed in stage 1…”

I have a lot of CLAUDE.md rules to restrict this stuff, but realize the “encapsulation” language is something I’m missing.

▲

jawilson2 2 hours ago | parent | prev | next [-]

Yeah, agreed. These have started popping up a lot more recently, where I get a 5 sentence paragraph explaining how function overloading works in c++.

▲

wrs 2 hours ago | parent | prev | next [-]

Claude Code and Opus 4.8 love to describe changes in comments (perhaps because that’s what’s on its “mind” at the time), like “this used to do A but that did a bad thing so now it does B”. I’ve almost convinced it that changes go in the commit message, not the comments.

▲

actionfromafar 2 hours ago | parent | prev | next [-]

Well, on the one hand, Hyrum's Law: "With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody."

so that can be useful information in some situations.

On the other hand, what a horrible out of date mess of comment that can turn out to be a little bit later. Taken as gospel by the next entity (human or llm) to massage that function.

▲

boredtofears 2 hours ago | parent | prev [-]

I have tried prompting it out and providing strong guidelines in my AGENTS.md against it, but I still get _way_ too many useless "explain the code" style comments no matter how much I try. I usually have to do something like "Look at all commits in the past X days and remove (DO NOT TRIM) all comments that are not truly exceptional"

Normally when I can't get claude to follow a prompt I try a lint hook, but it's tough to lint something that subjective.

▲

SoftTalker 2 hours ago | parent | prev | next [-]

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.

	▲	WillAdams 2 hours ago \| parent \| next [-]
		I really wish Literate Programming had caught on. The big problem is folks misunderstood it as documentation (arguably plain.tex should have also been the sourcecode for _The TeXbook_ and that it wasn't is a big part of this) --- it could be, but usually that's better as a separate text/chapter.... I've been trying to collect books on Literate Program/notable Literate Programs published as books: https://www.goodreads.com/review/list/21394355-william-adams... and I will note that my own programming took a quantum leap forward when I purchased and read: https://www.goodreads.com/book/show/39996759-a-philosophy-of... and applied its principles one chapter at a time to a project which I was able (w/ a bit of help) to get into Literate Programming form: https://github.com/WillAdams/gcodepreview/blob/main/literati...
	▲	hakunin 2 hours ago \| parent \| prev \| next [-]
		There was a phase, which I also got sucked into at the time, that comments are bad. Problem is, to make your code be so self-explanatory that it conveys business decisions, background stories for how you've arrived here, research-based choices made, you would have to name your variables and functions in a batshit_insane_way_that_obfuscates_behavior_among_the_names. It doesn't make anything better. Use short names where they're contextually clear. Use long names where they're contextually weird/non-belonging. Use comments to explain the "whys" of your code.
	▲	SomeHacker44 an hour ago \| parent \| prev [-]
		I still code this way.

▲

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

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

▲

saghm 4 hours ago | parent | next [-]

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 22 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.

▲

3 hours ago | parent | prev | next [-]

[deleted]

▲

dionian 2 hours ago | parent | prev [-]

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