|Syntactic Confectionery Delight|
You seem to have taken particular exception because you think I made no real case, but argued:
... on the basis of: commenting is so obviously good, that not commenting can *only* be the product of laziness and indifference; which is absolutely not the case for many of us that prefer minimal commenting.
Well... what I thought I'd done was to describe in broad terms what I consider to be the attributes of good commenting, and then to enumerate what I think are some of the benefits. I fail to see how that is starting from a position of "commenting is so obviously good", far less jump from there to an accusation of "laziness and indifference". I feel you've misrepresented what I said... but, hey ho, it's an imperfect world.
I agree that there is such a thing as excessive and pointless commenting -- which is made-work both for the original author and for later modifiers. In my assembler days I would despair of programmers who thought that every instruction required a comment saying what it was.
I'm not sure whether you are arguing for no comments at all, or whether the question is the degree and type of comments ? If the second, then I'd be interested to hear what you think represents "good" commentary.
However, you asked for an example. OK. I posted this some time ago. I haven't constructed it as a text book example of good commenting -- in any case, like most forms of writing the question is: "who is the audience ?". Alternatively, I can offer ensure.pm. I look forward to seeing them torn to shreds :-) [Looking back at the posting, there is quite a bit of background -- if you just want to look at the module, see here.]
I will also give an example of where, IMO, there is a shortage of comments. This is from numeric.c in the Perl 5.10.0 source.
I looked at this source to discover why Perl decimal to binary conversion is not correctly rounded. To cut a long story short, Perl_my_atof2() is a home-brew conversion routine, which makes a mess of some cases.
I wondered why the code doesn't use atof(), and therefore depend on the library writer's skill. There is no commentary to help. I understand, from responses to the bug report I submitted, that the code used to use atof() until its semantics changed in C99 ! Quite a lot of work went into Perl_my_atof2() -- I would have commented on why, at least.
The solution to the problem is to discard all the arithmetic in Perl_my_atof2() and replace it by something which checks that the incoming decimal number string is a valid Perl number, and feed the (possibly modified) string to the real atof(). I would happily bang out a patch to do that... except that it's struggle to work out what the code is expected to do, because there isn't anything at all to say why it is the way it is.
The issue is complicated by the problem of Locale. This is the code that uses Perl_my_atof2() -- I promise you, I have not removed any comments !
For me there are two issues here:
Obviously I could settle down and run some test cases, and reverse engineer the requirements. As it happens, I'm not that familiar with the effects of locale switching, which adds to the problem. Just a few comments would do to equip me with the information required to fix the bug...
...further, if I'm right about the two passes in Perl_my_atof being redundant -- a few comments might have helped others too !