I've been programming for well over 15 years and have watched myself move from the "comments are for wimps" mentality to the "document the hell out of everything" track.

There's a middle ground. The path to it starts by considering that comments have the potential to be a maintenance burden. The potential for burden increases with the volume of commentary. It gets to be a major nuisance during maintenance when a 2 line change means having to rework 20 lines of commentary. Human nature being what it is, somebody is going to forget to update a comment, and the world described by the commentary can begin to diverge from the truth of the code. Having two divergent stories is a bigger liability than one truth, the code, with no commentary at all.

Pod documentation carries an additional risk, if one follows the style of locating the pod either entirely before or entirely after the code it describes. Physical distance between code and its corresponding commentary increases the likelihood that the commentary won't be updated during maintenance.

The middle ground is to locate commentary close to the code it describes, and to write as little commentary as necessary. If comments are close to the code and there isn't an excess of verbiage, chances are greatly improved that the commentary will survive maintenance.

In reply to Re: Why I'm a Pod::Nazi by dws
in thread Why I'm a Pod::Nazi by Bobcat

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.