6 ms·

>True. But the flip side is that comments can outlive their relevance, accuracy, or purpose. >This is a good reason to reject most comments: they're an additio

>True. But the flip side is that comments can outlive their relevance, accuracy, or purpose. >This is a good reason to reject most comments: they're an additional maintenance cost that can't be automated. By the same line of reasoning one should reject most code. A comment that helps the next programmer who's going to look at the code is good. If/when the comment is obsolete, deleting it is easy. I'm saying this as someone who rarely includes comments in a first commit. Generally I add comments that answer questions that come up in code review, because it's likely that someone else looking at the code will have the same questions my reviewers have.

Ma8ee 6y ago
> By the same line of reasoning one should reject most code. Yes, you should reject all unnecessary code. If that is "most", then your project might have some problems. ;) > If/when the comment is obsolete, deleting it is easy. The hard part is to know if and when the comment is obsolete. It's way too often I stumble upon comments that contradicts the code. Is the code wrong? Is the comment wrong? Often the history reveals that the comment was correct at some earlier time, but the person changing the code didn't think about changing the comment. I think that the mechanism behind this is that after the first read through of the code we tend to stop seeing the comments.
- brlewis 6y ago
  In my experience, the mistake of updating code without updating the accompanying comment is commonly made, but does not commonly survive code review.
BurningFrog 6y ago
> If/when the comment is obsolete, deleting it is easy. And yet it unfailingly keeps not happening. Not because it's hard to do, but because it's easy to miss. Implementing every change both in code and comments can maybe be done, but I've neverseen it done, and I don't understand how you'd go about it.
- brlewis 6y ago
  Comments should be sparse, used only where code is not self-explanatory. If you follow that rule, spotting obsolete comments in code review is easy. I've seen it.
  - BurningFrog 6y ago
    I agree with being sparse. Can't say I've seen a great comment maintenance track record anywhere so far...

Ma8ee 6y ago

> By the same line of reasoning one should reject most code. Yes, you should reject all unnecessary code. If that is "most", then your project might have some problems. ;) > If/when the comment is obsolete, deleting it is easy. The hard part is to know if and when the comment is obsolete. It's way too often I stumble upon comments that contradicts the code. Is the code wrong? Is the comment wrong? Often the history reveals that the comment was correct at some earlier time, but the person changing the code didn't think about changing the comment. I think that the mechanism behind this is that after the first read through of the code we tend to stop seeing the comments.

brlewis 6y ago
In my experience, the mistake of updating code without updating the accompanying comment is commonly made, but does not commonly survive code review.

BurningFrog 6y ago

> If/when the comment is obsolete, deleting it is easy. And yet it unfailingly keeps not happening. Not because it's hard to do, but because it's easy to miss. Implementing every change both in code and comments can maybe be done, but I've neverseen it done, and I don't understand how you'd go about it.

brlewis 6y ago
Comments should be sparse, used only where code is not self-explanatory. If you follow that rule, spotting obsolete comments in code review is easy. I've seen it.
- BurningFrog 6y ago
  I agree with being sparse. Can't say I've seen a great comment maintenance track record anywhere so far...