Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
One reason these commenting discussions get so difficult is that good commenting is really a product of programming experience, and sometimes history. Depending on experience, one person's commenting on goals of the code is another person's commenting on mechanics.

Consider a block of code consisting of a while loop with internal variables named $high, $low, $mid. I think most experienced programmers skimming the code would assume that the loop is some kind of binary search algorithm. They might appreciate (at most) a very short comment saying #binary search right above the start of the while loop, but anything more than that would be annoying. On the other hand, if there was something weird about the use of a binary search in that context or it really wasn't a binary search, then any of the following comments might be appreciated:

  • #looks like binary search - but isn't - read carefully
  • #binary search - optimized using fiddle foo
  • #yes - there is a standard routine for this, but it is in a CPAN module and at the time of writing (2009-xx-xx) the client has insisted for reasons X,Y,Z that there be no external dependencies

But each of those comments requires a great deal of context and experience even to construct. A programmer who doesn't know what a binary search algorithm looks like is hardly going to know that he or she needs to comment their code when it looks like one but isn't.

On the other hand, I'm sure some of us can remember when we were first learning the ideas behind a binary search. Grasping each step of the algorithm was painful and we very much appreciated our professor or text book explaining each step of the algorithm and why it was done that way.

As a further thought, what does and doesn't need to be commented changes over time even for the software industry as a whole. Before the discussion of patterns became widespread, it would have been impossible to comment code using a visitor pattern with a one liner #process foo using visitor pattern.

Best, beth

In reply to Re: Why no comments? by ELISHEVA
in thread Why no comments? by targetsmart

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?

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

    How do I use this? | Other CB clients
    Other Users?
    Others pondering the Monastery: (8)
    As of 2019-11-21 14:40 GMT
    Find Nodes?
      Voting Booth?
      Strict and warnings: which comes first?

      Results (104 votes). Check out past polls.