|Perl: the Markov chain saw|
No programmer can expect to account for all maintenance programmer shortcomings, but that does not free you from the obligation to try.
I'm sorry, but we will probably have to agree to disagree on this. To my mind, that is exactly what it does do.
There is simply no way for me to predict what gaps there will be in the knowledge of any programmer that will see my code. Or what they will find difficult to understand. Or what idioms they will eshew as 'too complex'. I do not know who they will be, or what their experience levels will be. Or how many of them there will be. Or what their personal coding preferences, prejudices or blind spots will be.
Given that uncertainty, the best I could hope to do is include the entire contents of perldoc in a comment at the top of every program. Ridiculous you say, but it isn't. As far as understanding the vagaries, inconsistencies and idioms of Perl is concerned, that is the definitive answer. The idea that I could write it better is ludicrous. That it should be a part of my source files is more so.
No amount of documentation (too much, too little, or just right) will ensure that the maintenance programmer will read your documentation. Use comments and documentation.
What makes you think he would read the comments?
The first thing I do in most every piece of other peoples code I pick up is to throw away the comments (in a copy!). The second is to manually reformat the code to my personal preferences. The third is to 'fix' any obvious verbosities, by recoding them to use (my preferred) idiomatic constructs and discard any extraneous (used once intermediary) variables.
Only once I have been through the entire file, line by line, and any related files required to allow me to form an understanding of what the code actually does--not what the author thought it did--do I even consider going back and looking at the authors comments. It's often very illuminating with respect to the authors level of understanding of what he wrote :) And only after that process is complete do I consider myself even vaguely competent to consider modifying that code. Even then, if this is real code that I am about to modify, I may well feel the need to add a bunch of trace statements and run it before I will consider attempting to modify it. I never, ever take comments to be the truth.
Take those three comments you posted above. From those comments I can derive quite literally zero information about what that code, or the program they were a part of, is designed to do. You might, but then you wrote them. But to me, they are entirely and utterly meaningless in the absence of further information.
However, if you had posted the code, minus the comments, I'll bet that I could derive a whole lot more information than is included in those comments. Often as not, if there is a code bug, or a subtle potential bug there, I'll find it. But if I read your description of what you think you code is doing, before I read the code itself, when I do read the code, I'll probably not question it as closely, and so come away with the assumption that what you described it was doing, is correct.
Code is precise; words are not. Words are ambiguous and open to interpretation; code is not. The meaning of the words you use is subject to your education, your context, your prejudices, your mood, your experiences etc. etc. Your code suffers from none of these flaws. Programmers tend to comment those things that they personally found difficult to code or understand. They reflect their own abilities and knowledge, not that of the people they are (supposedly) writing the comments for. Even when you are your own maintenance programmer, you run the risk of influencing your own thought patterns back into the same (incorrect) groove you were in when your wrote that code.
One of my favorite debugging techniques, (for my own code when time and circumstances permit), is to simply abandon it for a while. Leave it as is and go do something else for a while before coming back to it and trying to understand it again. The intervening period of time doing something else, preferably something very different, has the effect of washing my mind of all the assumptions and conclusions that I had previously reached about a problem and allows me to focus on it afresh. To come at it from a different angle. And so often that allows me to see the assumptions I was making. And see the errors in those assumptions.
If I comment the code with those assumptions, then when I return to that code, I'm likely to fall right back into making the same assumptions, and the same errors.
I'll say it again. Extensive comments are redundant and dangerous. I use occasional and sparse comments when I feel they truly clarify a piece of code, but in general, my choice to not comment my code has nothing to do with being lazy. It is an explicit and conscious decision based upon my personal experiences of the quality of comments I've encountered and the value I perceive they have.
Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.