I heartily disagree Abigail's comment that people who document every sub are wrong. There is no such thing as too much documentation, no matter how redundant it may be.

Abigail's a pretty smart person, and I think the slip from "comment" to "document" was unintentional. Yes, you should always document your whole public API. Otherwise it's not really public, is it?

But don't waste my limited screen real estate on crap like this: 

  #
  # Class->foo() - returns the value of foo for the object
  #
  sub foo { $_[0]->{foo} }
Another commenting pet peeve: 
  # if $x is bigger than 10
  if ( $x > 10 ) {
      # set $x to $y modulus 50
      $x = $y % 50;
  }
  # otherwise, if $y is not equal to 50
  elsif ( $y != 50 ) {
      ...
  }
Argh! I hate that so incredibly much. Comments that simply tell me _what_ the code is doing are absolutely, utterly useless. Always assume that the next person does understand programming logic, assume that they understand Perl, etc.

Don't assume they know why something is the way it is, however. In the above code, I want to know why it's important to set $x to the $y modulus 50 only when $x is greater than 10.

There are a few exceptions to the "no walk-through comments" rule. Very complicated algorithms may deserve very careful step by step comments. This can help you as you code, in making sure that you're actually following the algorithm, and it helps future readers. And if you deliberately write less-than-clear code, for example as an optimization (after benchmarking and profiling, please), then it may be worthwhile to comment the what of the code.

But a good rule to follow is that if you think the what of the code is too hard to follow without comments, then you need to rewrite the code in a clearer manner.

In reply to Re: Re: Documenting Methods/Subs by autarch
in thread Documenting Methods/Subs by vek

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, details, 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, summary, 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.