Beefy Boxes and Bandwidth Generously Provided by pair Networks
more useful options

Re: Why no comments?

by ELISHEVA (Prior)
on Feb 01, 2009 at 08:57 UTC ( #740521=note: print w/replies, xml ) Need Help??

in reply to Why no comments?

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

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://740521]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (2)
As of 2020-10-24 20:43 GMT
Find Nodes?
    Voting Booth?
    My favourite web site is:

    Results (246 votes). Check out past polls.