Comment by jcgrillo
2 months ago
Comments are great until they diverge from the code. The "no comments, just self-explanatory code" reaction comes from the trauma of having to read hundreds of lines of comments only to discover they have nothing to do with how the code actually works, because over time the code has received updates but the comments haven't. In that case it's better to just have no comments or documentation of any kind--less cognitive overhead. This is a symptom of broken culture, but the breakage is the same kind that has managers salivating over LLM vibeslop. So I totally get where your colleagues might be coming from. Working within the confines of how things actually are it could be totally reasonable.
So don’t do that.
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.
This is honestly such a bad argument against comments.
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.
> that's their problem not mine
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.
I really can't imagine this ever becoming a real problem. Not once have I ever worked in a place where any kind of leadership would ever give a shit about comments nor anything else in the code itself. The lowest level leadership has ever gone is click a button to see if it works.
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.
3 replies →
You may be a bit overconfident about how clear you will be with your comments.
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.
Oh really? I'm overconfident in my ability to write and read simple clear text notes?
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.
1 reply →
And then you find out the dipshit that didn't keep the comments up to date was you all along
It wasn't.