No sweat. Me? i don't scatter pod. I 'cluster' it in one spot - i like mine at the very end. When i need to modify the POD, i use a split-screen mode in my text editor. That way i can see the method i am documenting easily. Remember, you are not suppose to be reading the POD while you are reading the code (i.e., in your text editor), you are suppose be reading POD via a POD viewer (perldoc). Second, small meaningless stuff is not even worthy of comments in the first place, IMHO. I will use a single # comment to put an author's name in if i grab code from the Monastery, but other than that, i don't bother. It is a waste of time. It's hard enough to keep the POD current with the code, why add another layer? (see Re (tilly) 2 (disagree): Another commenting question, for more on that.)

And while your suggestion of substituting in warn has been duly noted, that final blurb was an 'inside joke', a reference to the infamous use CGI or die; write up. I'll leave it intact, thank you. ;) 

use POD or die $!;

[download]

UPDATE:
I almost forgot about using POD as multi-line comments. Personally, i think that # comments are the uglier of the two: 

# function: foo
# input   : bar baz
# output  : qux
# precond : bar and baz are defined
# postcond: qux is defined
sub foo {
}

[download]
versus 
=for comment
 function: foo
 input   : bar baz
 output  : qux
 precond : bar and baz are defined
 postcond: qux is defined
=cut
sub foo {
}

[download]
Two extra lines, but you don't have to worry about prepending #'s. You don't have to have 'valid' POD to create a multi-line comment, by the way. Just a simple =for token to start and =cut to end.

UPDATE2
sigh ... you missed my points completely ... did you even read tilly's post?

jeffa

L-LL-L--L-LL-L--L-LL-L--
-R--R-RR-R--R-RR-R--R-RR
B--B--B--B--B--B--B--B--
H---H---H---H---H---H---
(the triplet paradiddle with high-hat)

In reply to (jeffa) 3Re: Perl script commenting assistant by jeffa
in thread Perl script commenting assistant by Wafel

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.