Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight
 
PerlMonks  

comment on

( [id://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

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



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others browsing the Monastery: (5)
As of 2024-03-29 08:41 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found