4 ms·

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"

hansonkd 3mo ago
The comments that drive the most homicidal behavior are outdated or inaccurate comments rather than no comments.
- minraws 3mo ago
  Both can be true at the same time, we can be equal opportunity murderers who treat lazy verbosity and hippester terse code.
- gowld 3mo ago
  Put your home address in the comments. Problem solved.
  - sejje 3mo ago
    I moved after I wrote the comment. It's hard to keep everything up to date.
- saghm 3mo ago
  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 3mo ago
    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).
    - AnimalMuppet 3mo ago
      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 3mo ago
        Nice, I love this. That's pretty satisfying.
    - saghm 3mo ago
      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)
  - mekoka 3mo ago
    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.
TimTheTinker 3mo ago
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.
- jawilson2 3mo ago
  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++.
- fphilipe 3mo ago
  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 3mo ago
    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 https://code.claude.com/docs/en/output-styles Maybe these would work better for such cases.
    - 3mo ago
deleted 3mo ago
[deleted]
SoftTalker 3mo ago
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 3mo ago
  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?ref=nav_mybooks&tag=literateprograms 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-software-design 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.sty https://github.com/WillAdams/gcodepreview/blob/main/literati...
- hakunin 3mo ago
  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.
dionian 3mo ago
sounds like a recipe for over-commenting. The code should be self-documenting. Comments are for the places where there are dragons.

hansonkd 3mo ago

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

minraws 3mo ago
Both can be true at the same time, we can be equal opportunity murderers who treat lazy verbosity and hippester terse code.
gowld 3mo ago
Put your home address in the comments. Problem solved.
- sejje 3mo ago
  I moved after I wrote the comment. It's hard to keep everything up to date.
saghm 3mo ago
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 3mo ago
  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).
  - AnimalMuppet 3mo ago
    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 3mo ago
      Nice, I love this. That's pretty satisfying.
  - saghm 3mo ago
    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)
- mekoka 3mo ago
  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.

TimTheTinker 3mo ago

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.

jawilson2 3mo ago
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++.
fphilipe 3mo ago
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 3mo ago
  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 https://code.claude.com/docs/en/output-styles Maybe these would work better for such cases.
  - 3mo ago

deleted 3mo ago

[deleted]

SoftTalker 3mo ago

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 3mo ago
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?ref=nav_mybooks&tag=literateprograms 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-software-design 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.sty https://github.com/WillAdams/gcodepreview/blob/main/literati...
hakunin 3mo ago
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.

dionian 3mo ago

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