Actually that section was discussing POD, and this thread is discussing inline comments. I agree with moving POD to the __END__ block. 
# What this function does
sub foo {
    #Something worth noting
    blah();
}

__END__

...

=head2 foo()

  my $result = foo(1,2);

[download]
The section of Best Practices that was mentioned is as follows:
Having decided to keep the documentation together, the obvious question is whether to place it at the start or the end of the file.

There seems to be no particular reason to place it at the beginning. Anyone who is looking at the source is presumably most interested in the code itself, and will appreciate seeing it immediately when they open the file, rather than having to wade though several hundred lines of user documentation first. Moreover, the compiler is able to do a slightly more efficient job it if doesn't have to skip POD sections before it finds any code to compile.

So place your POD at the end of the file, preferably after the _ _END_ _ marker so that the compiler doesn't have to look at it at all. Or, if you're using a _ _DATA_ _ section in your implementation, wrap the documentation in =pod/=cut directives and place it just before the _ _DATA_ _ marker.

In reply to Re^2: Are there any drawbacks to comments -- can they hurt the performance of Perl code? by imp
in thread Are there any drawbacks to comments -- can they hurt the performance of Perl code? by jira0004

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.