Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

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 !

NV Perl_my_atof(pTHX_ const char* s) { NV x = 0.0; #ifdef USE_LOCALE_NUMERIC dVAR; if (PL_numeric_local && IN_LOCALE) { NV y; /* Scan the number twice; once using locale and once without +; * choose the larger result (in absolute value). */ Perl_atof2(s, x); SET_NUMERIC_STANDARD(); Perl_atof2(s, y); SET_NUMERIC_LOCAL(); if ((y < 0.0 && y < x) || (y > 0.0 && y > x)) return y; } else Perl_atof2(s, x); #else Perl_atof2(s, x); #endif return x; }
For me there are two issues here:

  1. the key question is, why does it do Perl_my_atof2() twice ?

    Perl_my_atof2() is not a cheap operation. Who knows what it costs to switch the numeric locale. So it looks as though there must be some important semantic requirement here. I would have thought that merited some comment ?

    Suppose Perl_my_atof is given the string '123,456.789' -- if the locale has a ',' decimal point, then the answer is 123point456, otherwise it's 123 (duh). I'm missing something, I expect, but I cannot see why two passes are required or what problem it is supposed to solve. The author must have had to think this through... it would not have cost much to leave some notes for posterity ?

    Perl_my_atof2() itself worries about locale, and will (as far as I can see) accept either the current locale decimal point or '.'. I have a feeling that this means that the two passes in Perl_my_atof() are unnecessary -- if only I could be sure what they were for. If so:

    • I observe that there is no commentary to describe the acceptable form of numbers, so perhaps whoever wrote the two passes didn't fully understand what Perl_my_atof2() does ?

    • or, perhaps more likely, the two passes in Perl_my_atof() were required before Perl_my_atof2() was introduced, but whoever wrote Perl_my_atof2() couldn't see why either, and hence couldn't see that its locale handling is either redundant or makes the two passes redundant.

    A relatively small amount of "why" commentary would help a lot now. Who knows, a little bit of more general commentary might have helped in the past.

  2. sadly, the comment there is, is useless -- it tells you no more than what the code tells you.

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 !


In reply to Re^3: Why no comments? by gone2015
in thread Why no comments? by targetsmart

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others taking refuge in the Monastery: (7)
    As of 2019-11-21 08:16 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      Strict and warnings: which comes first?



      Results (104 votes). Check out past polls.

      Notices?