|Perl: the Markov chain saw|
You are heading towards exactly the same style of commenting that lead to one of the absolute worst monstrosities I have ever had the displeasure of working with. You doubt that anyone has ever complained about having too many comments. Well I have, and many excellent programmers that I know have, and your commenting style is exactly the kind of thing that makes me (based on painful experience) cringe.
Please do yourself and the next programmer a favour and pick up a classic like Code Complete or The Pragmatic Programmer and learn about the real maintainance problems that synchronizing code and comments will introduce. They are real and severe. Instead of having 2 documents (and creating a tremendous amount of work tidying up comments that experienced programmers know not to trust) attempt to have your code stand as a comment in and of itself. Take some time to break it up, structure it, use meaningful variable names. Use meaningful subroutines. Don't use globals.
I am sorry that I am coming across like a ton of bricks, but rather than trying to (in your words) shoot down arguments against overcommenting, you should try to understand them. What is the job of code? It is to instruct the computer in a way that a human can understand, and that humans later can figure out, refactor, and reuse with a minimum of work. Now when you run the program you can verify what the computer has been told. If you change it and run it, you can test whether the computer did the right thing. However if you change the human instructions, you do not find mistakes until after a human gets confused. And if you need to change what the instructions are, then you need to change both. In reality this does not happen. And trying to synchronize the two documents will be a constant real source of problems.
The solution is to, as much as is feasible, have the code itself stand as a comment. As merlyn pointed out, one of your (bad) examples of how to comment uses a variable $x and then in the comment explains what $x is and what you are doing. I cannot say strongly enough that I do not want to ever work with code that is written like this! If instead you took half the energy that you are currently wasting in writing and then formatting comments that experienced programmers know not to trust and instead spent it in structuring your code and giving your variables proper names, then your code will have a much better chance of being understandable to maintainance programmers. I should know what they want - after all I spend a lot of my time doing maintainance on things that other people wrote. :-)
For an example of what I mean take a look at Text::xSV. I wrote that last night in a couple of hours. Were it only meant for internal use, I would probably be missing the pod section, and the API comments that currently appear in the pod would be in front of the various functions. What I find interesting is that though many people have disagreed with me about commenting, they usually also say after seeing my code that they would have no problem working with it. Given that, I think that my opinions on how to make code easy to work with are worth something...
Also note that I don't actually write uncommented code. But my comments are about different aspects of the code than the mere mechanics of what each line is doing...
In reply to Re (tilly) 2 (disagree): Another commenting question,