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?

  • 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, 2012 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.
    – Chuck Dee
    Oct 27, 2012 at 20:18

1 Answer 1


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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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