>>>There is a whole school of thought that "all comments are lies" - usually also extended to Hungarian Notation (HN) and any sort of long, "descriptive" variable names. Anyone who's maintained an app written by someone else has gone on wild goose chases, or otherwise been burned by bad comments.
>>>
>>>I like Christof's example for generic functions. Discussing that a little further I can see cases where it would be easier to spot variable references in code if they are short and distinct (e.g. xxx, yyy, zzz) rather than SomeMeaningfulVariableName1, SomeMeaningfulVariableName2 etc. I've seen *way* too much of the latter.
>>>
>>>I still comment critical business logic, and other unique code.
>>
>>I would say, all comments are *possible* lies, but more possibly helpful (even if they are not still 100% accurate).
>
>Ah, but the devil is in the details. When you've been on a wild goose chase through someone else's code, it's more maddening when the comments that sent you there were *almost* correct, and looked credible.
>
>I remember one example: I was working on code that looked well-commented. At the top of the code were comments that explained the order of methods that were going to be called, and a short description of what each one did. One of the methods in the comments, call it "SomeComplexBusinessLogic()", was the "guts" of the routine.
>
>For some reason, I happened to quickly scan down the code a page or so to find where this function was called. What I actually found was a call to SomeComplexBusinessLogicv2().
>
>Note that SomeComplexBusinessLogic() still existed in the code base, and there was nothing in it that said "superseded by SomeComplexBusinessLogicv2()". It would have been all too easy to spend half a day analyzing that code and enhancing it. As it turned out, the v2 version was a complete refactoring so none of any work I would have done on v1 would have been applicable - it would have been a complete waste of time.
>
>Then, of course, there's the ultimate maddening experience - when you go to enhance some of your own code you may not have looked at in a couple of years, and you end up getting burned by your own comments < g >

<g> So what did you do with the comments, fix them, take them out, or leave them as they were?