4 ms·

I've seen this many times: ...thus they (comments) tend to diverge from actual implementation. It happens, you update/refactor code, and forget to update

I've seen this many times: ...thus they (comments) tend to diverge from actual implementation. It happens, you update/refactor code, and forget to update the comments. Thus the comments are outdated or worse not applicable anymore. Common mistake by less-detailed oriented developers. Begs the question, in this case is is better to have confusing/incorrect comments, or no comments at all?

seanmcdirmid 12y ago
No comments are better than bad comments. There is nothing worse than a misleading description.
- dspillett 12y ago
  I've always gone with the adage: if the comment and code do not agree, don't assume that either of them are correct. A bad description isn't just a problem in itself, it can indicate a worse problem sat waiting to jump out and bite as you walk by.
  - rtpg 12y ago
    comments might diverge from behaviour but the code, almost by definition (modulo some crazy magic happening/broken interpreter ) _is_ the behaviour.
    - seanmcdirmid 12y ago
      The best commenting system is a debugger stepping through the code. Unfortunately, I've yet to see a commenting style that is able to really document mental models about how the code works.
      - nirvdrum 12y ago
        SEURAT is a research project that attempted this. I was a test subject for it a while back and found it pretty interesting. But its implementation at the time was an Eclipse plugin that probably hasn't been kept up todate. You can find a paper on it on the ACM digital library: http://dl.acm.org/citation.cfm?id=1368215 http://dl.acm.org/citation.cfm?id=1368215 I'm sure the dissertation is available somewhere on cs.wpi.edu, too.
    - dspillett 12y ago
      > code, almost by definition _is_ the behaviour. Yes, but is it the intended and/or desired behaviour in all cases that the codepath in question will be expected to experience? That is the problem, especially in code that deals with rare edge cases so is not run often, and/or covers many circumstances where it is right but is wrong for one set of inputs that no one thought to test before (or since that code last changes).
sheepmullet 12y ago
" ...thus they (comments) tend to diverge from actual implementation." In my experience comments are no more likely to diverge than tests are. With tests you have the advantage that they must compile. With comments you have the advantage that they are inline/interspersed with your code and so get read every time the code is read. "It happens, you update/refactor code, and forget to update the comments." So then the next developer to read that part of the code notices that the comment doesn't make sense, or is not well written, and they update it. No different than if they notice poorly named/misleading functions or variable names or a dozen other code smells. No big deal and certainly not a good case for commenting less.
- kasey_junk 12y ago
  "With comments you have the advantage that they are inline/interspersed with your code" Just as a heads up, there are lots of testing paradigms that have the tests inline with the code it is testing. That they aren't the default in most languages is most disappointing.

seanmcdirmid 12y ago

No comments are better than bad comments. There is nothing worse than a misleading description.

dspillett 12y ago
I've always gone with the adage: if the comment and code do not agree, don't assume that either of them are correct. A bad description isn't just a problem in itself, it can indicate a worse problem sat waiting to jump out and bite as you walk by.
- rtpg 12y ago
  comments might diverge from behaviour but the code, almost by definition (modulo some crazy magic happening/broken interpreter ) _is_ the behaviour.
  - seanmcdirmid 12y ago
    The best commenting system is a debugger stepping through the code. Unfortunately, I've yet to see a commenting style that is able to really document mental models about how the code works.
    - nirvdrum 12y ago
      SEURAT is a research project that attempted this. I was a test subject for it a while back and found it pretty interesting. But its implementation at the time was an Eclipse plugin that probably hasn't been kept up todate. You can find a paper on it on the ACM digital library: http://dl.acm.org/citation.cfm?id=1368215 http://dl.acm.org/citation.cfm?id=1368215 I'm sure the dissertation is available somewhere on cs.wpi.edu, too.
  - dspillett 12y ago
    > code, almost by definition _is_ the behaviour. Yes, but is it the intended and/or desired behaviour in all cases that the codepath in question will be expected to experience? That is the problem, especially in code that deals with rare edge cases so is not run often, and/or covers many circumstances where it is right but is wrong for one set of inputs that no one thought to test before (or since that code last changes).

sheepmullet 12y ago

" ...thus they (comments) tend to diverge from actual implementation." In my experience comments are no more likely to diverge than tests are. With tests you have the advantage that they must compile. With comments you have the advantage that they are inline/interspersed with your code and so get read every time the code is read. "It happens, you update/refactor code, and forget to update the comments." So then the next developer to read that part of the code notices that the comment doesn't make sense, or is not well written, and they update it. No different than if they notice poorly named/misleading functions or variable names or a dozen other code smells. No big deal and certainly not a good case for commenting less.

kasey_junk 12y ago
"With comments you have the advantage that they are inline/interspersed with your code" Just as a heads up, there are lots of testing paradigms that have the tests inline with the code it is testing. That they aren't the default in most languages is most disappointing.