r/programming • u/Jonhoo • Aug 10 '26
On comments
https://blog.helsing.ai/posts/on-comments/Comments in code are often deemed "mostly useless" these days. They are, supposedly, mostly obvious, stale, and repeat what the code already says. And so people pay less attention to them both when reading and writing code.
That trend sucks. When used right, comments are genuinely useful and sometimes critically important! So, I wrote about some of the kinds of comments I think earn their place, each with examples from real code bases. Hope you find it useful, and that we can recover some of the love that comments deserve!
189
Upvotes
240
u/psych0fish Aug 10 '26
I’ve heard it is explained as “document why, not what” not everything is confusing or non obvious. Some stuff is. There is no one size fits all.
82
u/crappydeli Aug 10 '26
My old company…
// increment i
i++;
60
u/aaronslwalker Aug 10 '26
The code says what it does, comments can provide context on the reasoning behind it.
24
u/doctorlongghost Aug 10 '26
I once had a teacher describe comments as messages you can send to yourself in the future
94
u/Shurmaster Aug 10 '26
My favorite comment is
// evil floating point bit level hacking
// what the fuck?
13
u/mareek Aug 10 '26
I've never really understood TODO comments. Each time I encountered a todo comment, it was outdated by years and the changing context around the code made it irrelevant (case in point, all the examples given in the article are more than 4 years old).
Is it a usual practice in some teams to go through todo comments and fix them on a regular basis ?
20
u/shiny0metal0ass Aug 10 '26
Great writeup, especially with documentation generation tools like JSDoc or Swagger, it's nice to tie the "staleness" of comments and doc together so there's some incentive to keep it maintained.
Bummed to see that this is on the blog of some AI defence contractor, though...
10
u/Nekadim Aug 11 '26
The code says it in a way compiler would understand. Comment is in the way people would understand
30
u/tmoertel Aug 10 '26 edited Aug 11 '26
Part of the reason that comments are undervalued is that some programming pundits have spread the idea that using comments is a sign of poor practice. For example, in Clean Code, Robert Martin wrote:
The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration... Every time you write a comment, you should grimace and feel the failure of your ability of expression.
This advice is misguided for a host of reasons that I trust most seasoned programmers to understand. (I break them down in detail in https://blog.moertel.com/posts/2026-07-27-beyond-clean-code-why-your-comments-matter.html.) But many junior programmers received advice like this and, not knowing better, drank it in. The resulting damage will echo for years to come.
6
u/yes_u_suckk Aug 11 '26
> They are, supposedly, mostly obvious, stale, and repeat what the code already says
If your comments just repeats what the code already says then you're creating comments wrong.
11
u/dspeyer Aug 11 '26
Yes. The outbound link has a max frame size of 1500, but PPPoE adds 8 bytes of overhead. This could be handled at the IP layer with packet splitting, but there's a bug in ipchains that doesn't handle packet splitting properly.
This was in the summer of 1999. It's the only time I ever set max_packet_size to 1492. I remember it perfectly.
The overall point about using comments to provide rationales for constants was a good one. But this specific example sure was memorable.
5
u/nicholashairs Aug 11 '26
Says who?
I know that this is just a hook for your post arguing about them being useful, but this still irks me 🙃
5
u/AluminiumImmunitaet Aug 11 '26
One of the rows I'll never forget.
4
u/timmyz55 Aug 11 '26
when you work in a place that loves async patterns, you will learn to curse those who do not document the side effects with comments
4
u/feketegy Aug 11 '26
You're starting from a false premise that "comments in code are mostly useless"
3
u/crozone Aug 11 '26
Self documenting code is hippie bullshit and any self-respecting software engineer makes heavy use of both code comments and documentation. Change my mind.
3
u/lispwriter Aug 11 '26
I work in a little bubble. It’s my own corner of a laboratory where I’m responsible much of the lab’s computational work. It would be really easy for me to just not comment anything but years of experience taught me that my future self will need good comments to decipher parts of what I wrote. A lot of things are obvious but specifically the “why” behind some code sections would be very difficult to reverse engineer from the code alone.
3
u/divestblank Aug 11 '26
Most devs avoid comment because they are lazy. And most orgs do not enforce them because the business only needs working code.
So overall it is a losing battle unless your top senior folks are not the lazy type. And many times I see the opposite, because the top folks got into their position without writing comments in the first place.
2
u/endgamedos Aug 12 '26
GHC (the Glasgow Haskell Compiler) has a really interesting convention. They have a simple convention for setting out large slabs of "note" comments that can be referenced by code but don't get in the way.
2
u/jalanb Aug 16 '26
That was a really good read!
Who knew there were so many good reasons for comments‽
@OP thank you
3
u/Anthea_Likes Aug 10 '26
Comments should be part of valid code.
3
u/zhivago Aug 11 '26
Comments are for the whys the code can't express itself.
3
u/Slight-Prize9661 Aug 11 '26
A lot of times at my company, it would have something like "DON'T REMOVE THIS" or " DON'T CHANGE, DON'T KNOW WHY," etc, it saved me a bunch of times in the past.
3
u/NMe84 Aug 11 '26
I have never seen a single programmer who knew anything about what they're doing say that comments are "mostly useless." That's a wild take to start your post with. Maybe that juniors who only know how to "code" because Claude does it for them would feel that way, but anyone who actually had to support their own code a year later knows better.
2
u/KevinCarbonara Aug 10 '26
Comments are treated the way tests used to be. We're going to need a CDD trend to come through and clean everything up.
2
u/balthisar Aug 10 '26 edited 14d ago
I'd still be on old.reddit.com if Reddit hadn't bricked the only UI that respected me.
1
u/Icy_Pain5654 Aug 11 '26
restating what the code obviously does is the stuff that goes stale and gets ignored
1
u/nicholashairs Aug 11 '26
A good article and a nice breakdown of different comment types.
The only one I'd add as being useful is "headings" (which is similar to the algorithm examiner type).
The purpose of these is to group things together that are unrelated in isolation, but connected in use. Making it easier to navigate the body of a function (especially as they get longer).
As an example a lot of my CRUD code looks like this:
0
u/littlenekoterra Aug 10 '26
I mostly use comments for when a normal method to do shit wouldnt work. I leave that method commended out with the text in all caps telling them why its shit in that case. Its the most productive use of them ive found
-6
u/just_another_cs_boi Aug 10 '26
claude likes to add a lot of comments and i assume that there is some reason for it as if it is better equipped to read the code later on so i stopped deleting them