Stare at that carefully.

Then please do me the same favor. In my first post, I wrote quite clearly:

The "why not what" model of commenting is a really good idea

I had already expressed my agreement with the previously stated idea that comments should focus on areas other than what most people comment on. The reason I wrote what I did was that some people's advice "don't comment badly" was being expressed as "don't comment." I merely wanted to reassert the importance of comments for future developers.

Secondly the very verbosity of the comments led you to use a useless variable and a confusing comment. You claim you wouldn't use such a variable name in practice, but I only have what you wrote to judge by. And in what you wrote you used a useless variable name and a useless - confusing - comment.

Really? I also wrote this:

###########################################################
#
#   Here are some comments on the following code.
#   It does stuff.
#   Its cool.
#
###########################################################
[download]

Do you suppose that is an accurate reflection of the type of comments I would put in real code? If you're going to use what I write to judge by, use all of it. I wasn't attempting to give examples of "real" comments and their content, because like I said that had already been expressed, and I agreed with it. I was trying to point out that A. comments are necessary and B. you can find ways to stick them in clearly and readably wherever they may be necessary.

Now you claim that the style of commenting that I demonstrated is what you were attempting to advocate

After reading your subsequent list of style points, I see that we are farther apart than I had thought from viewing one small piece of code. I would like to say that I still agree with the content that you chose to include in your comments. However, there were a few areas that I took issue with. Out of politeness and benefit of the doubt, I had assumed that these were merely oversights, but after reading your style-guide I can see that these were conscious decisions, that I would like to comment on (no pun intended).

If the function is not documented, it is not public

Are you saying that you never document a function that is not part of a public interface? If so, that is severely negligent. The purpose of comments is not solely, or even primarily, to describe the interface. Comments exist for the benefit of people who might need to maintain or modify the code. There is no reason to assume that because a function is not part of the public interface that it is magically immune to the need for update.

If the function name starts with an _, it is probably not even (usefully) callable

OOC, I've never seen this before, is it commonly used? If not, then how is that useful for other people?

Function names describe what they do

Really, so get_row and _get_row do what, the same thing?

Variable names describe what they do

Hmm, let's see. In one short example I find the following variables: $lookup, @data, @allowed, $q_sep, $match_sep, $expected, $piece, $req, $opt, $default, @res, $bad, and $sep. So in some 200 lines you managed to declare 13 variables that give no indication of what they do or why they were declared.

Now, I have to say that I more or less agree with the other points you mentioned. And I really would like to reiterate that I'm not trying to be a jerk, or to attack you personally (I say this because I know I have a very aggressive argument style, which doesn't reflect my emotional opinions of the person I'm arguing with--really!). What I'm trying to point out is that every programmer's own code always makes more sense to him than it will to anyone else. The variable and function names that make oh so perfect sense to you now mean nothing to the next guy who comes to read your code six months later.

And all of the points that you cautioned against are valid and accurate. It is important to make sure that comments are not so specific that they need to be updated continually with every minor code change. It is important that every comment should be written to add something useful to the reader's understanding. "There is no such thing as too many comments" was obvious (or so I thought) hyperbole, attempting to make the point that every programmer since first we did away with punch-cards has always thought he needed less comments than he did.

You are obviously a good programmer, and obviously a better one than me. However, that is part of my point. SE4's write the programs that SE1's get stuck trying to maintain. The threshold of what qualifies as "non-obvious" varies greatly. You seem to code under the impression that whatever makes perfect sense to you will make just as much sense to everyone else.

Some people drink from the fountain of knowledge, others just gargle.