I’m not saying comments are magic or anything. It takes work to keep them in sync with the code.
It’s a useful goal. Not a rule that gets you out in jail if yo fail.
It doesn’t mean you can blindly trust comments. I treat all code, and comments, with skepticism until I can understand and run it.
I'm gonna note down my reasons for doing things and other information I deem useful, and if some other dipshit 5 years from now when I've moved on comes along and starts changing everything up without keeping the comments up to date that's their problem not mine. There was never anything wrong with my comments, the only thing that's wrong is the dipshit messing things up.
Doesn't matter what I do, the dipshit is going to mess everything up anyway. Those outdated comments will be the least of their worries.
IME unfortunately that's not actually the case. It very much is your problem, as the architect of the original system, unless you can get yourself transferred to a department far, far away. I've never managed that except by leaving the company.
To be clear, I don't believe it should be this way, but sadly unless you work in an uncommonly well run company it usually is.
And if anyone has a problem with comments existing it's trivial to find/replace them out of existence. Literally a one minute job, if you actually think the codebase would be better without them.
This is such a humongous non-issue it's crazy man.
The “dipshit” doesn’t mess everything up for fun. They don’t understand the comments written by the previous “dipshit” and thus are unable to update the comments.
Here's what I think. I think you guys heard the "self-documenting code" BS and ate it up, and now you're grasping at straws to defend your cargo cult position, inventing these "problems" to justify it.
If you're looking at some code and there's a comment saying something that doesn't make sense to you, maybe that's a clue that you're missing a puzzle piece and should take a step back maybe talk to some people to make sure you're not messing things up? Maybe, for a non-dipshit, that comment they don't understand could actually be helpful if they put some effort into it?
Also just to be clear I don't think this is a likely occurrence unless someone doesn't know squat about the codebase at all - my comments generally assume very little knowledge. That's their whole purpose - to inform someone (possibly me) coming there without the necessary background knowledge.
It just isn't feasible to include the why of everything in the code itself. And it sure as hell is better to include some info as comments than none at all. Otherwise a bug will often be indistinguishable from a feature.
And I don't think dipshits mess things up for fun. I think they just suck. They're lazy and stupid, as most developers are. If I'm there I can use reviews etc to help them suck less, if I'm not they're free to wreck my codebase with reckless abandon and nothing I do will make any difference. I cannot safeguard my codebase against that so there's no point in trying and the fact that this is your argument should make you stop and reconsider your position because it's far fetched as fuck.
Or how would you name methods and variables to explain why some payment reconciliation process skips matching for transactions under 0.50 EUR and just auto-approves them, because the external payment processor rounds differently than the internal ledger at sub-euro amounts, creating mismatches that were flooding the finance team's exception queue in 2013, explained more under Jira issue ZXSV-12456 and more details are known by j.doe@myorg.com. The threshold was chosen after analyzing six months of false positives, when it's any higher someone being undercharged doesn't get caught. I don't think autoApproveThreshold = 0.50 or anything like that would get the full context across, even if the rules themselves are all code.
I think surely you can have both! Code should explain itself as often as possible, but when you hit a wall due to some counter-intuitive workarounds being needed, or some business rules or external considerations that you need to keep track of, then comments also make sense. Better than just putting everything in a Jira issue somewhere, given that it often won't be read by you or others and almost certainly will not be read by any AI agents (unless you have an MCP or something, but probably uncommon), or spending hours trying to get the code to explain something it will never explain well. I've had people ask me about things that are covered in the README.md instead of reading it.
Then the question becomes how often we look in the version control history for the files that we want to touch.
Which of these is more likely:
A) someone digging into the full history of autoApproveThreshold and finding out that they need to contact j.doe@myorg.com or reference ZXSV-12456
B) or them just messing the implementation with changes due to not reviewing the history of every file they touch
If someone is doing a refactor of 20 files, they probably won't review the histories of all of those, especially if the implementation is spread around a bunch of years, doubly so if there are a bunch of "fixes" commit messages in the middle, merge commits and so on. I've seen people missing out on details that are in the commit log many, many times, to the point where I pretty much always reach for comments. Same goes for various AI tools and agents.
Furthermore, if you want to publish a bit of code somewhere (e.g. Teams/Slack channel, or a blog), you'd need to go out of your way to pull in the relevant history as well and then awkwardly copy it in as well, since you won't always be giving other people a Git repo to play around with.
It's not that I don't see your point, it's just that from where I stand with those assumptions a lot of people are using version control as a tool wrong and this approach neither works now, nor will work well for them in the future.
It's more or less the same issue as with docs in some Wiki site or even a separate Markdown file (which is better than nothing, definitely closer than a Wiki, especially if the audience is someone who wants an overview of a particular part of the codebase, or some instructions for processes that don't just concern a few files; but it's still far removed from where any actual code changes would be made, also a downside of ADRs sometimes).
This is a good goal. You should strive to make the code explain itself. To write code that does not need comments.
You will fail to reach that goal most of the time.
And when you fail to reach that goal, write the dang comments explaining why the code is the way that it is.
Alternately, you can say the same about informative variable names or informative function names. "If I change the function then the name is no longer accurate". You don't say that because function names and variable names are short and clear and are close to the problem at hand. Do the same with comments.
Which is why the copilot hyper-verbosity is harmful. Comments need to be terse so your eyes don't filter them out as noise.
Gonna try and use that throughout my life. Thanks!
