5 ms·

Don't listen to this guy. Comment your code, because if its in production, your most likely not be the only hands that touch it! Someone down the line will ha

Don't listen to this guy. Comment your code, because if its in production, your most likely not be the only hands that touch it! Someone down the line will have to review it, change it or modify it. It saves both time and effort, if you comment the code. Just do it.

lmm 13y ago
Write code that other people can review, change or modify. If you're coding right, comments should rarely be necessary for that (and indeed would often just be a distraction).
IanCal 13y ago
> Just do it. Seconded. I've got an algorithm here, and the comments are very helpful. In one place, an array is iterated over backwards which is important and would trigger a few edge cases if it wasn't the case. A quick comment to explain why it's being done makes it easier to read and less likely someone will change it without understanding the consequences.
- MetaCosm 13y ago
  Or, you know tests. Having a "defensive" comment (explaining some critical corner case) is just terrible, write a test that exposes it so code can be refactored. "WARNING" comments are a really bad thing.
  - IanCal 13y ago
    Or, you know, both. Why not leave a comment explaining why a non-obvious code block was written. It's not an either-or situation. I've left a before because of a subtle GC bug triggered only on particular hardware, which could not be replicated in the development environment, and would only be revealed by a particular coincidence in timings. How do you test that?
lawn 13y ago
Or they will simply change or modify the code and leave the comment? Now the comment doesn't help, it's actually detrimental.
- dllthomas 13y ago
  Perhaps testable comments?
  - jdbernard 13y ago
    Why should we keep adding more complexity overhead to our languages and toolkits instead of finding people we can trust to do the job right?
    - dllthomas 13y ago
      Because there is no one we can trust to always do the job right, and so a large code base will accumulate cruft over time. Just how carefully do you search out any possible comment referencing code you change? It's not always going to be adjacent.
      - jdbernard 13y ago
        That's true, but at some point you cannot automate quality craftsmanship. Making comments part of the automated compile/test process in my opinion crosses the line and would be more detrimental than helpful. In this specific case I would prefer to add code review and emphasize practices like adjacency of comments to code. Code should be reviewed on a regular basis as well. We all make mistakes, but I think a habit of putting at least two eyes on it and of coming back periodically to review past work is better.
        dllthomas 13y ago
        I don't pretend to know it's a good idea, and there's undoubtedly poor ways to implement it, but I think it's worth exploring. Adjacency of comments to code helps, but not everything can be adjacent to everything else, and when necessarily disparate code necessarily interacts it merits a comment that cannot be local to both. Putting multiple eyes on the code is great, but 1) isn't prevented by what I propose, 2) isn't going to be perfect (and can perhaps be done more effectively with fewer things to have to check), and 3) sometimes isn't possible (if someone is working alone, for instance). As John Carmack recently put it, on a large project "[e]verything that is syntactically legal that the compiler will accept will eventually wind up in your codebase."
ZeroGravitas 13y ago
But some people won't read the comments. Or the article.
- pachydermic 13y ago
  Yeah, but I think his example of good code was pretty confusing. I still think it's a good idea to section off your code into smaller modules - each module should complete one 'step' of the process (whatever that means for your particular program) - and each module should have a short comment at the begging of the section explaining what it's inputs/outputs are or generally why it's there. Some comments for exceptionally tricky stuff isn't a bad idea, but like other people said they are often ignored and might get out of sync with the code that's actually there. But I still think some comments are better than absolutely no comments...
  - koblenski 13y ago
    Sorry for the confusing code. I took a look back at it after reading some of the comments here, and I found that I or Blogger had mangled the post. Almost half of it was missing right out of the middle. It's updated now, so hopefully it makes more sense.
vidarh 13y ago
And this is how we end up with comments that documents what the code used to do ten revisions ago.
- dkuntz2 13y ago
  You must be doing comments wrong. If they explain the why, they should still be relevant. Or people should rewrite them when they adjust the code...
  - vidarh 13y ago
    If they explain the why, they may be justified, but they will still eventually become invalid when the code is changed to do something with a different rationale. And yes, people should rewrite them when they adjust the code, but like so many other things: In any reasonably large code base it sooner or later gets neglected because the code still runs and passes all tests without it. If you want "documentation" that will stay up to date, you either need an extremely rigorous development process, which pretty much nobody has, or your documentation needs to be in the form of test cases that will break when the documentation is no longer valid. I 30+ years of writing code, I've don't think I've ever come across a project of any reasonable size that haven't had substantial comments that were outdated. I would love to see such a beast - it'd be a little bit like encountering a unicorn.
- talmand 13y ago
  If one cannot be bothered to update corresponding comments when updating code then I suppose they'll have problems updating the separated documentation as well.

lmm 13y ago

Write code that other people can review, change or modify. If you're coding right, comments should rarely be necessary for that (and indeed would often just be a distraction).

IanCal 13y ago

> Just do it. Seconded. I've got an algorithm here, and the comments are very helpful. In one place, an array is iterated over backwards which is important and would trigger a few edge cases if it wasn't the case. A quick comment to explain why it's being done makes it easier to read and less likely someone will change it without understanding the consequences.

MetaCosm 13y ago
Or, you know tests. Having a "defensive" comment (explaining some critical corner case) is just terrible, write a test that exposes it so code can be refactored. "WARNING" comments are a really bad thing.
- IanCal 13y ago
  Or, you know, both. Why not leave a comment explaining why a non-obvious code block was written. It's not an either-or situation. I've left a before because of a subtle GC bug triggered only on particular hardware, which could not be replicated in the development environment, and would only be revealed by a particular coincidence in timings. How do you test that?

lawn 13y ago

Or they will simply change or modify the code and leave the comment? Now the comment doesn't help, it's actually detrimental.

dllthomas 13y ago
Perhaps testable comments?
- jdbernard 13y ago
  Why should we keep adding more complexity overhead to our languages and toolkits instead of finding people we can trust to do the job right?
  - dllthomas 13y ago
    Because there is no one we can trust to always do the job right, and so a large code base will accumulate cruft over time. Just how carefully do you search out any possible comment referencing code you change? It's not always going to be adjacent.
    - jdbernard 13y ago
      That's true, but at some point you cannot automate quality craftsmanship. Making comments part of the automated compile/test process in my opinion crosses the line and would be more detrimental than helpful. In this specific case I would prefer to add code review and emphasize practices like adjacency of comments to code. Code should be reviewed on a regular basis as well. We all make mistakes, but I think a habit of putting at least two eyes on it and of coming back periodically to review past work is better.
      - dllthomas 13y ago
        I don't pretend to know it's a good idea, and there's undoubtedly poor ways to implement it, but I think it's worth exploring. Adjacency of comments to code helps, but not everything can be adjacent to everything else, and when necessarily disparate code necessarily interacts it merits a comment that cannot be local to both. Putting multiple eyes on the code is great, but 1) isn't prevented by what I propose, 2) isn't going to be perfect (and can perhaps be done more effectively with fewer things to have to check), and 3) sometimes isn't possible (if someone is working alone, for instance). As John Carmack recently put it, on a large project "[e]verything that is syntactically legal that the compiler will accept will eventually wind up in your codebase."

ZeroGravitas 13y ago

But some people won't read the comments. Or the article.

pachydermic 13y ago
Yeah, but I think his example of good code was pretty confusing. I still think it's a good idea to section off your code into smaller modules - each module should complete one 'step' of the process (whatever that means for your particular program) - and each module should have a short comment at the begging of the section explaining what it's inputs/outputs are or generally why it's there. Some comments for exceptionally tricky stuff isn't a bad idea, but like other people said they are often ignored and might get out of sync with the code that's actually there. But I still think some comments are better than absolutely no comments...
- koblenski 13y ago
  Sorry for the confusing code. I took a look back at it after reading some of the comments here, and I found that I or Blogger had mangled the post. Almost half of it was missing right out of the middle. It's updated now, so hopefully it makes more sense.

vidarh 13y ago

And this is how we end up with comments that documents what the code used to do ten revisions ago.

dkuntz2 13y ago
You must be doing comments wrong. If they explain the why, they should still be relevant. Or people should rewrite them when they adjust the code...
- vidarh 13y ago
  If they explain the why, they may be justified, but they will still eventually become invalid when the code is changed to do something with a different rationale. And yes, people should rewrite them when they adjust the code, but like so many other things: In any reasonably large code base it sooner or later gets neglected because the code still runs and passes all tests without it. If you want "documentation" that will stay up to date, you either need an extremely rigorous development process, which pretty much nobody has, or your documentation needs to be in the form of test cases that will break when the documentation is no longer valid. I 30+ years of writing code, I've don't think I've ever come across a project of any reasonable size that haven't had substantial comments that were outdated. I would love to see such a beast - it'd be a little bit like encountering a unicorn.
talmand 13y ago
If one cannot be bothered to update corresponding comments when updating code then I suppose they'll have problems updating the separated documentation as well.