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.
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.
> 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.
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.
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.
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.
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.
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.
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.
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.
> 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.
FB's main monorepo was named WWW, and you needed to refer to it every 5 minutes, so everyone pronounced it "dub-dub-dub". A surprisingly hard habit to break once you leave their employment
This app is a dream come true for me. As a user I'm heavily invested in Spotify but I've grown more and more irritated with their client. Especially the recommendations, which thankfully are largely absent from your client.
Would love a setting to also remove the "Made for you" section, as well as the "Recommended for you" section, both on the home page.
I was using Spicetify to customize the official client to this effect, using CSS.
We are seeing a slow but steady stream of small breaking changes, designed to gradually piss off everyone involved. While avoiding a large breaking change that attracts a load of bad publicity.
Sadly this strategy is the only good idea they've had in years.
And you can dismiss them.
reply