[seanmcdirmid]

The comments are meant to be read and used to understand code. So you must test them like any other artifact to ensure that they are a net positive and not a net negative. Programmers make mistakes, which hopefully fail a test or at least cause a crash. Because comments can't be executed, neither of those will happen; they have to be verified manually

[AlisdairO]

Isn't that fairly easy to do during a code review?

[dllthomas]

Only when all comments only refer to local information. There is nothing to check that the comment in that other file that refers to this code was correctly updated.

Some system of backrefs could handle this, of course, but I'm not aware of anything in use...

[dragonwriter]

> Only when all comments only refer to local information. There is nothing to check that the comment in that other file that refers to this code was correctly updated.

The only time a comment should refer to non-local information is to document an assumption or basis of the local code, which is still correct information about the local code as long as it is the assumption/basis of the local code, even if the assumption is (or later becomes) false.

Of course, it would be useful to have a way to verify the information about the assumptions to see if they have become false, but that's not about validating the comment, that's about validating the code it comments, since if the assumption is false, it is quite likely that the code needs to change (and this may not be something that unit testing the local code can discover, as such comments often are not about correctness but about choosing a less-than-obvious alternative correct approach for optimization, or to work around a quirk of the code being called, etc.)

[dllthomas]

I'm not sure I disagree. In practice, though, I certainly encounter comments communicating nonlocal information ("This is used in ..."), and of course these are the least likely to remain accurate. "All comments is local" is something we should start drumming into people - I don't think anyone ever said this to me explicitly.

[seanmcdirmid]

Sure, code review is a very manual approach.

[AlisdairO]

Yes, what I mean is, if you're doing code review then there's virtually no additional cost - you're looking over the changes anyway. It doesn't matter that the process is manual if you're already doing it. If you're not doing code review, then you perhaps either have some organisational issues or you have coworkers who are sufficiently responsible that you can trust them to do basic code hygiene work like keeping comments up to date.

[seanmcdirmid]

I think comments would be more difficult to review than code, since you'd have to carefully make sure they are meaningful by examining the code, without the context of the programmers involved. Alternatively, you could add comments during code review to document the review and basically redo the comments on each review...maybe.

Comments also break flow and get in the way of code reading, but could probably just be hidden during review.

[dragonwriter]

> I think comments would be more difficult to review than code, since you'd have to carefully make sure they are meaningful by examining the code, without the context of the programmers involved.

Actually, that only makes them hard to review if you are trying too hard, which defeats the purpose of reviewing comments -- if it is hard to validate the utility of a comment without the context of the programmer involved, its a bad comment and needs, at a minimum, to be clarified.

After all, the whole point of a comment is to communicate information to a future person who lacks the context of the programmer involved.

[mmhammer]

It's manual whether with a tool or without. We like using a tool because it automates the process. We find teams are more thorough in their reviews with a tool. We're also distributed, so it helps with collaboration too.