Hacker News Reader

Comment by anthracis417 | Hacker News Reader

Forgive my ignorance, but why and how would you test a comment? They don't do anything, there is no instruction for the machine to understand or run.

View on HN

He's referring to the problem of comments becoming out of sync with the code they're referring to. Not everyone updates comments as they update code.

And those people deserve a special place of torment all their own. How hard is it really to update, or at least delete comments that are no longer relevant when you modify the code?

It's not that it's hard, it just may not be apparent that you need to do so.

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

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

Sure, code review is a very manual approach.

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.

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.

> 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.

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.

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...

> 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.)

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.

Brings up an interesting point about perhaps using natural language processing to determine correctness of a comment. That would be prettty cool.

If you could use NLP to verify the comment, then what would the point of the comment be? Comments are for those aspects of a program that are invisible to the compiler and IDE, the intent.

Maybe my view of NLP is more sci-fi than reality, but I think you're missing what I meant. If you can use NLP to prove that your comment - ie the intent - which IS invisible to the compiler and IDE, then that might be cool. Practical, probably not. But I'd still be very impressed at the implications if this was possible within some error margin.

Then you will read the comment that says to do one thing but the program will do a completely other thing. I don't see any problem, do you?

That's why good comments are about explaining WHY you're doing something, or HOW to use the code, and possibly making the code itself clearer but only if there's no way to do that by introducing better variable and method naming.

Comments are highly valuable but like any tool they can be abused, or done in such a way that they don't make things better.

The point is that comments can become out of date, and there's no automated way to enforce they stay up to date.

Reply on news.ycombinator.com