3 ms·

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

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.

sfn42 7mo ago
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.
- jcgrillo 7mo ago
  > 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.
  - sfn42 7mo ago
    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.
    - jcgrillo 7mo ago
      Leadership doesn't need to give a shit about the code to cause the cultural defect that leads to comments not being maintained. All they need to do is set the conditions which prevent code owners from having the agency to reject shoddy work. In my experience this always happens. It can manifest as either: (1) "flat" organization where everyone owns everything and therefore nobody has the authority to reject a PR or (2) "rubber stamp" culture where people who reject shoddy work are "not a team player" and therefore performance defective. So far every company I've worked at has one or both of these symptoms. Working in the confines of those systems, it's not an irrational choice to decide that comments and other forms of documentation aren't worth trying to maintain, and are therefore detrimental.
      - sfn42 7mo ago
        Reject a PR? I provide feedback on PRs. Then the owner of the PR adjusts it to accommodate my feedback and once I'm happy with it I approve it and we merge. If you're working in a place so cancerous that you can't just leave a comment on a PR reminding someone to update the comment they forgot to update I don't know why you're still there. This is called code review and it's common practice. If all you ever do is approve PRs then you're not doing code review and you might as well skip the whole PR step and let people merge into main as they please. In any case your argument still just boils down to "I work with a bunch of stupid lazy dipshits" so why bother doing anything at all then? Write comments, don't write comments, write tests, don't write tests, do whatever the fuck you want because you're surrounded by useless dipshits and nothing you do matters anyway. Might as well write some comments for your own sake, everything's a ball of mud anyway it doesn't matter. I'm gonna keep doing what I think is right in my sane corner of the world. And honestly I don't believe you. I think these excuses are just that. Excuses. I've been around quite a bit and haven't seen anything like you describe. Sure there's plenty of lazy dipshits but you don't have to sink to their level.
        cindyllm 7mo ago
        [dead]
- krupan 7mo ago
  And then you find out the dipshit that didn't keep the comments up to date was you all along
  - sfn42 7mo ago
    It wasn't.
- ozozozd 7mo ago
  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.
  - sfn42 7mo ago
    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.
    - prepend 7mo ago
      I agree with and appreciate your comment. I’ll also note that I’ve worked with developers who didn't like git blame because someone might misinterpret the results. I think some people want excuses for poor work, rather than just working as correctly as possible.
prepend 7mo ago
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.

sfn42 7mo ago

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.

jcgrillo 7mo ago
> 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.
- sfn42 7mo ago
  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.
  - jcgrillo 7mo ago
    Leadership doesn't need to give a shit about the code to cause the cultural defect that leads to comments not being maintained. All they need to do is set the conditions which prevent code owners from having the agency to reject shoddy work. In my experience this always happens. It can manifest as either: (1) "flat" organization where everyone owns everything and therefore nobody has the authority to reject a PR or (2) "rubber stamp" culture where people who reject shoddy work are "not a team player" and therefore performance defective. So far every company I've worked at has one or both of these symptoms. Working in the confines of those systems, it's not an irrational choice to decide that comments and other forms of documentation aren't worth trying to maintain, and are therefore detrimental.
    - sfn42 7mo ago
      Reject a PR? I provide feedback on PRs. Then the owner of the PR adjusts it to accommodate my feedback and once I'm happy with it I approve it and we merge. If you're working in a place so cancerous that you can't just leave a comment on a PR reminding someone to update the comment they forgot to update I don't know why you're still there. This is called code review and it's common practice. If all you ever do is approve PRs then you're not doing code review and you might as well skip the whole PR step and let people merge into main as they please. In any case your argument still just boils down to "I work with a bunch of stupid lazy dipshits" so why bother doing anything at all then? Write comments, don't write comments, write tests, don't write tests, do whatever the fuck you want because you're surrounded by useless dipshits and nothing you do matters anyway. Might as well write some comments for your own sake, everything's a ball of mud anyway it doesn't matter. I'm gonna keep doing what I think is right in my sane corner of the world. And honestly I don't believe you. I think these excuses are just that. Excuses. I've been around quite a bit and haven't seen anything like you describe. Sure there's plenty of lazy dipshits but you don't have to sink to their level.
      - cindyllm 7mo ago
        [dead]
krupan 7mo ago
And then you find out the dipshit that didn't keep the comments up to date was you all along
- sfn42 7mo ago
  It wasn't.
ozozozd 7mo ago
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.
- sfn42 7mo ago
  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.
  - prepend 7mo ago
    I agree with and appreciate your comment. I’ll also note that I’ve worked with developers who didn't like git blame because someone might misinterpret the results. I think some people want excuses for poor work, rather than just working as correctly as possible.

prepend 7mo ago

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.