I find that POD is great for documentation for users. That is for documenting interfaces to class/instance methods, basic usage, etc. It lends itself to sitting just outside a sub{} block, at the beginning and at the end of a piece of code.

But for good comments of the # variety, I really like Steve McConnell's suggestions in "Code Complete". Instead of writing code first you write pseudocode first-- discrete, plain English descriptions of what is to happen in this piece of code, indenting to show sub-blocks and such. Then you prepend # to each line (actually I'd just start with them there). Then you insert actual code in between those comments-- having already "rehearsed" the procedure mentally, writing the code is halfway automatic. Then if you have anything in your code that really isn't readable (but mostly it is because you use sensible variable names, keep your statements simple, etc etc, right?) you make a quick note what that does. Ditto if anything your code in has side-effects that may not be visible just reading that bit of the code. Of course, this sort of precommenting with pseudocode takes some discipline, but I find when I use this technique my code is a lot better.

In reply to (ichimunki) Re: Why I'm a Pod::Nazi by ichimunki
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.