4 ms·

Comments are great for developers. I like having as much design in the repo directly. If not in the code, then in a markdown in the repo.

• hk__2 6mo ago
  This is also a great way to ensure the documentation is up to date. It’s easier to fix the comment while you’re in the code just below it than to remember “ah yes I have to update docs/something.md because I modified src/foo/bar.ts”.
  • CharlieDigital 6mo ago
    People moving docs out of code are absolutely foolish because no one is going to remember to update it consistently but the agent always updates comments in the line of sight consistently. Agent is not going to know to look for a file to update unless instructed. Now your file is out of sync. Code comments keeping everything line of sight makes it easy and foolproof.
• KronisLV 6mo ago
  Meanwhile, some colleagues: "Code should have as little comments as possible, the code should explain itself." (conceptually not wholly wrong, but it can only explain HOW not WHY and even then often insufficiently) all while having barebones/empty README.md files more often than not. Fun times.
  • Pxtl 6mo ago
    > the code should explain itself. 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.
    • bandrami 6mo ago
      But you will also fail to keep the comments and code synchronized, and the comment will at some point no longer describe why the code is doing whatever it does
      • jaxn 6mo ago
        But copilot code review agent is pretty good at catching when code and comments diverge (even in unrelated documentation files).
      • Pxtl 6mo ago
        Which is why you're reviewing changes. I haven't memorized what every line of code does, if it was worth commenting then it was confusing-enough that it needed the comment and so I'll read the comment to make sense of the code being changed. If I don't read the comment that means the comment was too far from the confusing code. 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.
        • bandrami 6mo ago
          Yeah, my point has basically nothing to do with AI and is the argument against comment blocks in general. It's bad to store information in two places.
  • jcgrillo 6mo 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.
    • sfn42 6mo 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 6mo 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 6mo 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.
  • zingar 6mo ago
    Actually good naming does plenty to explain the why. And because it’s part of the code it might actually be updated when it stops being true.
    • KronisLV 6mo ago
      How would you use good naming to explain this https://en.wikipedia.org/wiki/Fast_inverse_square_root#Overview_of_the_code https://en.wikipedia.org/wiki/Fast_inverse_square_root#Overv... 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.
      • zingar 6mo ago
        You’ve correctly identified that naming isn’t sufficient for all communication. Name the things that stay constant in the code and explain the things that vary with a particular implementation in version control messages. Version control as a medium communicates what context the message was written for, which is far more appropriate than comments.
        • 6mo ago
  • alexandre_m 6mo ago
    Comments are mostly useful when they explain the why, not the what.
  • AbstractH24 6mo ago
    HOW vs WHY is a great destination between design and documentation. Gonna try and use that throughout my life. Thanks!