No. Naming and good architecture are. Intuitive folder trees. Concise docs. Clear separation of concerns such that naming can suffice.
The more comments you need to ‘map’ your code, the worse of a job you’ve done.
boxesnlines 15 hours ago [-]
I absolutely agree that those things should take priority, but I think those things can only go so far and there's a threshold of complexity beyond which there will always be some benefit to comments. You can absolutely reduce the need for 'signposts' if you avoid creating a maze.
As others have said, you didn't always build the maze. Or you built a lovely intuitive path and then were hit with an unexpected new requirement that forced you to add twisty little passages. Or, like me, you're not a perfect being and had to compromise based on some complication you didn't expect.
pyrale 17 hours ago [-]
> Smart developers don’t write mazes.
You don’t choose what your forebears have written, though.
jorisw 17 hours ago [-]
Patching that up by using comments as a 'map' isn't the right way to deal with that. Refactors and rearchitecture are. Putting in comments just helps procrastinate what's necessary.
pyrale 15 hours ago [-]
> Patching that up by using comments as a 'map' isn't the right way to deal with that.
There is no right way. Only grey ones that help relieve pain for the team.
> Refactors and rearchitecture are.
Yeah... if you have the cash and the people. Usually, mature codebases are driven by limited investment with proven business value, because the sweet VC money is no longer there (or never was, in some industries).
If you don't, reachitecturing is vanishingly rare, and your refactor budget is limited and you spend it carefully. If a piece of code hasn't moved recently but still comes up frequently when onboarding newcomers, documenting the code may be more profitable and less risky than changing it. It also helps preparing a case for a potential refactor.
stingraycharles 16 hours ago [-]
Rewrites require a lot of effort, significantly more than just adding comments. It’s a pragmatic tool until you actually have the time to do the rewrite.
jorisw 16 hours ago [-]
I never said rewrites.
And the more you put in procrastination-encouraging half-solutions, the worse your code base gets.
adrianN 16 hours ago [-]
It's difficult to refactor and rearchitect without first understanding what's there and why.
jorisw 16 hours ago [-]
And yourself putting in comments is the solution to that?
adrianN 13 hours ago [-]
It depends on how much time you can spend on the task. If you're allowed to write proper documentation about architecture and requirements that is probably better. If you're just drive-by fixing the code, then good comments are a lot better than nothing.
misswaterfairy 15 hours ago [-]
Though the onus is on us to improve what our forebears wrote, for the sake of our own and others' future.
pyrale 14 hours ago [-]
I agree with that. I'm just not sure all of us have the same leeway to improve the codebase, and the cost isn't the same either. When you have less means, you spend them more sparingly.
Tade0 17 hours ago [-]
I'm afraid this all gets thrown out the window nowadays.
Unless I tell them not to, LLMs lean on slapping verbose comments of the worst kind - describing the code instead of the reasons for putting it there.
I ask them to write comments in ASD-STE100 Simplified Technical English, but all I really get from that is tersness.
Also the other day I stumbled upon a huge pile of documentation and I'm still trying to figure out if it's human or machine written. I stopped reading it half way through as I figured that perhaps it wasn't written for humans to read.
rootlocus 16 hours ago [-]
The most WTF comments are the ones that describe how the code looked during a rewrite session with no commits. It writes bad code, I ask it to rewrite it, and it leaves a comment saying why the previous implementation was bad, with no history in git of the previous implementation.
Edit: changed the LLMs pronoun to it.
stakhanov 14 hours ago [-]
LLMs do this to communicate with their future selves to avoid retracing what turned out to be the garden path.
Another pattern is where they put comments in multiple places in the code to say that those need to be kept in sync in a very particular way ...that sort of thing has always been considered a code smell, but seems to be the post-AI "new normal": it's cheaper for the AI to leave it to its future self to have to make every change in multiple places than it is for its present-day self to do the refactor.
Before AI, writing code that worked was costly and structuring it well, while you were at it, didn't increase your cost all that much. Now, AI has reduced the cost of writing badly-structured but working code, while it hasn't reduced the cost of writing well-structured code all that much. Since no one who decides about this sort of thing has given two craps about structure, ever, bad structure is just what we're left with now.
The day will come when codebases will be completely unintelligible to humans. The best example is when AI actually refers to code in comments with actual line numbers. No human would ever do that or find that useful if another human did it, because it would be next to impossible for a human to keep the line numbers properly updated after edits and they would soon all be wrong and meaningless.
You'd have to go very far back in computing history to get to where we learned not to do that. Was there ever programming with goto's referencing line numbers instead of named labels? If so, this would be that.
gmueckl 12 hours ago [-]
Opus 5 has this habit and it makes any kinds of revisions of plain text almost useless. I can restrain it a little by adding instructions to just describe the current state, but we all know how dumb LLMs are at following these kinds of instruction.
kuschku 16 hours ago [-]
Who is this "he" you're talking about? Or were you referring to an LLM? If so, the correct pronoun would be "it".
Your english is really good, except for that little mistake.
rootlocus 16 hours ago [-]
I am 100% guitly of anthropomorphizing LLMs, sorry.
onion2k 16 hours ago [-]
Unless I tell them not to, LLMs lean on slapping verbose comments of the worst kind - describing the code instead of the reasons for putting it there.
I wonder if that's actually useful for an LLM though. It's additional context that should steer the LLM not to change the code to do something else.
TeMPOraL 16 hours ago [-]
> Unless I tell them not to, LLMs lean on slapping verbose comments of the worst kind - describing the code instead of the reasons for putting it there.
Well, my LLMs are "smarter" than yours. They'll describe why the code is there. They'll even try to keep these comments in sync with code as it makes changes.
This includes describing the "why" behind the change even on code affected only accidentally, e.g. by reformat or reindent. And, if it wrote some code and then later learned half of it is wrong, it'll remove the offending parts and leave comments telling what used to be there, and why it isn't anymore.
Same for commit/PR messages.
May or may not be related to a recent tendency in Opus/Fable models I noticed, to eagerly turn user feedback into rules, self-correct by adding more rules, and then when some rule fails, correct it by adding a counter-steering rule - accumulating rules until eventually getting lost in them.
AIorNot 15 hours ago [-]
Everyone disagrees about Good Architecture and it changes with new technologies btw
Years ago I worked on a project that had a n tier architecture and facade pattern for the frontend
It was good architecture for the lead developer who set it up but bad for the new team who need to update the tech
So comments and docs are both valuable
Nowadays with AI the calculus has changed once more
jarofgreen 18 hours ago [-]
> Typically keep comments on a single line without line breaks — if a comment is useful, developers will scroll to read them, if it’s not they can easily scroll past it.
Disagree. Personally that sounds like a massive barrier to reading the comment to me. Limited width column text is generally regarded as easier to read, make your comments easier to read. Especially as I probably have the code open in a limited width window, as that's what I expect from code.
medwards666 15 hours ago [-]
Yeah, this particular bullet point almost made me stop reading the rest of the article thinking that the author has zero idea what the hell they're on about...
someothherguyy 17 hours ago [-]
What? You don't like horizontally scrolling 6000 columns to read something?
Yeah, if IDE's allowed code folding of comments then the authors original problem (having to scroll past comments they thought weren't useful) wouldn't be that big a deal.
there are also extensions for vscode that do this, vim plugins, etc
dozerly 18 hours ago [-]
Who doesn’t have soft wrapping enabled in 2026? Line breaks are irrelevant
jarofgreen 17 hours ago [-]
If line breaks really were irrelevant, the author wouldn't have felt the need to give a tip all around optimising line breaks.
Personally, I would have hoped by 2026 we had better IDE's and tools for managing code in text files such that developers with different preferences for a number of characters in a column or things like how you display comments can be accommodated. Yet still teams end up arguing about what standard to use.
Lindby 17 hours ago [-]
Soft like breaks in a code editor? That's insane
Cockbrand 17 hours ago [-]
And so the war began.
This is a bit like vim vs Emacs - everyone should be able to use their favorite setup, and the formatting should not get in the way of the engineer's preferences.
ezrabuenk 17 hours ago [-]
I, in fact, do not have wrapping enabled in my IDE....
tacomagick 17 hours ago [-]
You never wrote Java I see
xboxnolifes 17 hours ago [-]
Java is why I don't have line wrapping enabled. It makes code unreadable when everything needs to be wrapped.
verdverm 17 hours ago [-]
Who makes assumptions about how others do things in 2026? Line breaks are apparently relevant, review agents complain about them, soft breaks are super annoying for vim motion users, opinions are still like ani
lintfordpickle 16 hours ago [-]
I disagree with the overall sentiment of this article. I wouldn't say comments are never useful, because they certainly can be. But once verbose commenting becomes the norm, people (and now especially LLMs) will overuse them, making the code unnecessarily obtuse and difficult to read. And the point about maintenance is real.
There are also a couple of 'pointless' statements in the article itself:
> "Use a combination of in-line and standalone comments, depending on the situation"
isn't that just every kind of comment?
boxesnlines 15 hours ago [-]
(I am the author)
The point of that statement was to run counter to the standards of "always us X type of comments" that some teams adopt. My suggestion is that there isn't a "correct" type of comment that you should always use, but rather that it's highly situational.
It's really a parallel to grammar in any other kind of language - there isn't a singular 'correct' way to structure a piece of writing into paragraphs, but it's also typically incorrect to treat each sentence as a paragraph or to avoid paragraphs entirely and write everything as a single block of text.
It's unthinkable that a team of writers would ever try to standardise on "never use paragraphs" or "every line is a paragraph", but some programming teams do exactly the equivalent of that!
lintfordpickle 15 hours ago [-]
Thanks for the reply. I didn't mean to be dismissive or discredit the article.
The problem you described is real, and one I face daily at work. Anecdotally, every time we've tried to curate the comments and organize them (especially when referencing external documentation, as you also mentioned), it invariably ends up becoming stale and just another point of contention down the road.
I'm now more of a proponent of either not commenting, or putting the context and rationale in the commit message instead.
2 days ago [-]
jdw64 17 hours ago [-]
Sounds good. I've lost count of how many mazes I've made. Just call me the Architect of the Labyrinth.
monster_truck 17 hours ago [-]
Once again I am asking, who is this person and why do they think they are qualified to tell me what's best?
boxesnlines 15 hours ago [-]
Hello, I am that person. I have been programming for a long time, but I'm not trying to make any claims that my experience means I know any better. The claim is simply that modern coding practices often produce code that is difficult to navigate and that useful comments and documentation can deliver great benefits.
I do make some suggestions on how to approach those things, but they're simply suggestions based on my own experience, I'm not trying to assert any kind of absolute correct approach.
caporaltito 11 hours ago [-]
To be honest, this is half of what is posted here. And 99% of the advices you will get in life.
deadbabe 15 hours ago [-]
You don’t need maps. You need search. Introducing: ripgrep.
aktenlage 15 hours ago [-]
I use Ag integrated in the editor all the time. But while it is indispensable for me, I wouldn't say that this helps in all situations, nor is it the best tool to find connections in many situations.
deadbabe 14 hours ago [-]
There are tools for finding connections. You really do not even need to open files unless you are going to edit them.
If, like me, you're trying to compile it, don't forget to set the
flag in gcc, so: Then run it as:> In code, comments are our signposts
No. Naming and good architecture are. Intuitive folder trees. Concise docs. Clear separation of concerns such that naming can suffice.
The more comments you need to ‘map’ your code, the worse of a job you’ve done.
As others have said, you didn't always build the maze. Or you built a lovely intuitive path and then were hit with an unexpected new requirement that forced you to add twisty little passages. Or, like me, you're not a perfect being and had to compromise based on some complication you didn't expect.
You don’t choose what your forebears have written, though.
There is no right way. Only grey ones that help relieve pain for the team.
> Refactors and rearchitecture are.
Yeah... if you have the cash and the people. Usually, mature codebases are driven by limited investment with proven business value, because the sweet VC money is no longer there (or never was, in some industries).
If you don't, reachitecturing is vanishingly rare, and your refactor budget is limited and you spend it carefully. If a piece of code hasn't moved recently but still comes up frequently when onboarding newcomers, documenting the code may be more profitable and less risky than changing it. It also helps preparing a case for a potential refactor.
And the more you put in procrastination-encouraging half-solutions, the worse your code base gets.
Unless I tell them not to, LLMs lean on slapping verbose comments of the worst kind - describing the code instead of the reasons for putting it there.
I ask them to write comments in ASD-STE100 Simplified Technical English, but all I really get from that is tersness.
Also the other day I stumbled upon a huge pile of documentation and I'm still trying to figure out if it's human or machine written. I stopped reading it half way through as I figured that perhaps it wasn't written for humans to read.
Edit: changed the LLMs pronoun to it.
Another pattern is where they put comments in multiple places in the code to say that those need to be kept in sync in a very particular way ...that sort of thing has always been considered a code smell, but seems to be the post-AI "new normal": it's cheaper for the AI to leave it to its future self to have to make every change in multiple places than it is for its present-day self to do the refactor.
Before AI, writing code that worked was costly and structuring it well, while you were at it, didn't increase your cost all that much. Now, AI has reduced the cost of writing badly-structured but working code, while it hasn't reduced the cost of writing well-structured code all that much. Since no one who decides about this sort of thing has given two craps about structure, ever, bad structure is just what we're left with now.
The day will come when codebases will be completely unintelligible to humans. The best example is when AI actually refers to code in comments with actual line numbers. No human would ever do that or find that useful if another human did it, because it would be next to impossible for a human to keep the line numbers properly updated after edits and they would soon all be wrong and meaningless.
You'd have to go very far back in computing history to get to where we learned not to do that. Was there ever programming with goto's referencing line numbers instead of named labels? If so, this would be that.
Your english is really good, except for that little mistake.
I wonder if that's actually useful for an LLM though. It's additional context that should steer the LLM not to change the code to do something else.
Well, my LLMs are "smarter" than yours. They'll describe why the code is there. They'll even try to keep these comments in sync with code as it makes changes.
This includes describing the "why" behind the change even on code affected only accidentally, e.g. by reformat or reindent. And, if it wrote some code and then later learned half of it is wrong, it'll remove the offending parts and leave comments telling what used to be there, and why it isn't anymore.
Same for commit/PR messages.
May or may not be related to a recent tendency in Opus/Fable models I noticed, to eagerly turn user feedback into rules, self-correct by adding more rules, and then when some rule fails, correct it by adding a counter-steering rule - accumulating rules until eventually getting lost in them.
Years ago I worked on a project that had a n tier architecture and facade pattern for the frontend
It was good architecture for the lead developer who set it up but bad for the new team who need to update the tech
So comments and docs are both valuable
Nowadays with AI the calculus has changed once more
Disagree. Personally that sounds like a massive barrier to reading the comment to me. Limited width column text is generally regarded as easier to read, make your comments easier to read. Especially as I probably have the code open in a limited width window, as that's what I expect from code.
https://en.wikipedia.org/wiki/Code_folding
there are also extensions for vscode that do this, vim plugins, etc
Personally, I would have hoped by 2026 we had better IDE's and tools for managing code in text files such that developers with different preferences for a number of characters in a column or things like how you display comments can be accommodated. Yet still teams end up arguing about what standard to use.
This is a bit like vim vs Emacs - everyone should be able to use their favorite setup, and the formatting should not get in the way of the engineer's preferences.
There are also a couple of 'pointless' statements in the article itself:
> "Use a combination of in-line and standalone comments, depending on the situation"
isn't that just every kind of comment?
The point of that statement was to run counter to the standards of "always us X type of comments" that some teams adopt. My suggestion is that there isn't a "correct" type of comment that you should always use, but rather that it's highly situational.
It's really a parallel to grammar in any other kind of language - there isn't a singular 'correct' way to structure a piece of writing into paragraphs, but it's also typically incorrect to treat each sentence as a paragraph or to avoid paragraphs entirely and write everything as a single block of text.
It's unthinkable that a team of writers would ever try to standardise on "never use paragraphs" or "every line is a paragraph", but some programming teams do exactly the equivalent of that!
The problem you described is real, and one I face daily at work. Anecdotally, every time we've tried to curate the comments and organize them (especially when referencing external documentation, as you also mentioned), it invariably ends up becoming stale and just another point of contention down the road.
I'm now more of a proponent of either not commenting, or putting the context and rationale in the commit message instead.
I do make some suggestions on how to approach those things, but they're simply suggestions based on my own experience, I'm not trying to assert any kind of absolute correct approach.