That was a big project - about a year - and all I did was comment the code. Why? Because nobody other than a very few people understood the debugger. Reading that code with no comments is sort of like hearing half a phone conversation, as the debugger is really just the Perl side of the execution-time hooks that make debugging possible. The comments clarify the things that are happening elsewhere that are important to the the debugger code that's just been called from someplace else. That contextual info is important - and it can't be in the code; it has to be in the comments. Yes, you could switch back and forth between the debugger source and the Perl source, but you'd have to understand the Perl core pretty well. With comments, you can just read and understand in much less time with much less effort.

Compare the 5.004 debugger to the 5.8.8 one to see the difference between the uncommented source and the commented. I think it was worth doing, as (among other things) Devel::ebug and the beginnings of the debugger tests in the Perl core tests came out of that. I firmly believe it was because the stuff you should "just get from the code" was finally laid out, explained, and made possible to follow.

I also believe that nearly anyone who's basically familiar with Perl can now read the debugger source and actually get something out of it other than a headache, even if it's a resolution to never ever write code like that.

Comments, as I mentioned, are not meant to tell you what the code can tell you itself; they are meant to tell you what decisions went into putting that code there in the first place, and the context in which these decisions made sense. As in the kernel bug noted, the reason for the decision is sometimes more important and considerably more complex than the code itself is. When a few characters make the difference between a root exploit and secure code, put in the comment!

Writing comments is writing; if the comments are good, then they communicate an arc of logic from point start to finish. The combination of the comments and the code should tell you more than either could alone. If they don't then the comments are wasted space - but should be condensed, corrected, and made to communicate, not simply discarded!

The comments and code conflict? There are several possible reasons, but one important possibility is that there really was a disconnect between the desire and the implementation, and that the code is actually wrong. It may be functioning and passing its tests, but it may nonetheless not be what was actually intended. It may be very hard to find out what was really wanted - and the code and comments don't help - but the fact that they conflict communicates something important that the code alone would not and cannot. If you simply strip the comments and then look at the code, you've thrown away data. Never a good idea when you're looking at code you don't know well (meaning that you know what was wanted, what it's doing, and why).

I honestly find an approach that says "never" comment or "always" delete comments suspect; it's as if the programmer had decided that they didn't like else clauses. Sure, you can write code that's functionally equivalent without them, but you've made a choice that deliberately makes the code's primary job - communicating to the next programmer - more difficult, and I think that's a bad choice.

Comments are as integral a part of the language, and if you've decided never to use them, you really should think about that, and be sure it's not (for instance) compensating for feelings of insecurity. "I'm so good I don't need comments! Really I am!"

I prefer to know that I need comments some places, and I make sure I put them in at those places. I don't think I'm not as good because I comment; I think I'm more considerate and better cognizant of my abilities by doing so. Maybe the next programmer really will be so good he or she doesn't need comments. Let's hope the one after the decommenter is as good as the decommenter thinks he or she is.

Know your audience, and be honest and pragmatic. Not every programmer is going to be as brilliant as every other. You're not going to be as brilliant every day. Make sure the average programmer (and you) will be able to read the code with the comments and get as much out of it as the brilliant one can without the comments. This is eminently possible, and worth it, in my opinion.