[lazyjones]

> And then you end up with a codebase which indicate A but comments which clearly spell out B, and you as a maintainer have no idea what to believe.

Can you name a few examples where you encountered this? In my career (30 years programming) I've never seen it. I believe it's a common, poor excuse for not writing enough comments.

The benefits of comments are well-understood. For me personally they often helped compensate sloppy code, (non-obvious) assumptions and prevented bad solutions because I reconsidered while writing (embarrassing) comments.

when you have to maintain a large codebase modified thousands of times in 15+ years, every single comment is invaluable.

[tigershark]

Then you must have been very lucky, I have seen it happening probably hundreds of times in a mere 15 years on the job. The inconsistencies that I experienced ranged from doc strings stating to pass a parameter that didn’t exist any more, parameters with different names, parameters with the correct names but in different orders. As per actual comment I have seen plenty of time comments like

    //here we go baby!
    //do not touch!
    //1 ... //2 ... //3 .. //8

The last one apparently was to indicate the order of some overengineered stuff that could have been written properly.

//This happens only for CompletedOrders (while in reality it was the opposite)

//This calculates the notional in the same currency (while it was converting it in GBP)

//This is extremely important, never delete (and after that there was a bunch of commented code)

Honestly I don’t remember all of them, I tend to use my memory for more important things, but I bet that if you had seen only 1/10 of the bad comments that I have encountered you would have a different opinion. Btw in your post you are explaining exactly why I hate comments:

“For me personally they often helped compensate sloppy code” - the solution is obviously to fix the sloppy code, not to write a comment because you are too lazy to fix it

“(non-obvious) assumptions” - this is probably the only legitimate reason to write a comment.

“and prevented bad solutions because I reconsidered while writing (embarrassing) comments.” - this has nothing to do with the comments given that at the end you didn’t write it. Thinking more about the code instead of trying to comment it gives you the same result, if not even better.

[lazyjones]

I was asking specifically about comments that directly contradict the code in a way that confuses the reader. If obsolete comments like "never delete" stand before commented code, what makes you think the commented code is actually used or useful?

> “(non-obvious) assumptions” - this is probably the only legitimate reason to write a comment.

If that's what you think, I rest my case...

[majikandy]

Are you serious? Almost every codebase that has comments has code that doesn’t exactly match the comments. Main obvious reason being that the comments aren’t executed whereas the code is. Sure meticulous attention to detail could keep the two in the sync. But you are suggesting that they have always been in sync for any code you’ve looked at?

As someone who is clearly a fan of comments, are you saying you’ve never modified a comment to make it more accurate to what the code is doing?