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
in reply to Re: Another commenting question,
in thread Another commenting question,
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
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...