Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

In refactoring code, I came across code that had comments. Looking closer at the comments, I could see that the code was clearly not doing what the comments said.

Without access to the coder nor documentation, and without clear direction regarding the code (i.e. defects as to the fact that the code is operating incorrectly), is the best practice to assume that the code is correct, and clean up the comments?

share|improve this question

migrated from codereview.stackexchange.com Oct 27 '12 at 18:23

This question came from our site for peer programmer code reviews.

8  
Best practice is to assume neither is correct. Delete the comments, figure out what it should be doing, and make sure it does that. –  Kevin Oct 27 '12 at 0:47
    
@Kevin - Well, as I said, there is no documentation as to what it should be doing, unfortunately, or I'd do just that- the only documentation is the comments. I am loath to leave it as is because it would just basically punt the problem, but without clear direction as to the original intent, there's only the code and the comments to tell me what direction to move in. –  wraith808 Oct 27 '12 at 20:18
add comment

1 Answer

up vote 8 down vote accepted

This is where source control is helpful. See if the code ever matched the comments. If it did match but was changed later, see if the check-in comment and other changes made in the same check-in adequately explain the reason for the change. If it does, then update the code comments.

If you can't get any hints from source control, you pretty much have to assume either code or comments could be wrong. Figure out what the consequences to changing the code to match would be. If it improves the code, then do it. If it doesn't, then remove or change the comments.

If you can't tell on your own, your code doesn't automatically become the authoritative source on how the program should behave, your customer always retains that role. If both behaviors look equally valid to you, ask your customer which they prefer. Point out the existing behavior, your reasons for suspecting it may need to be changed, and the consequences for doing so.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.