Not sure it has to do with prerogatives. Clearly, keeping the comments at the function head is the simplest to _maintain_. But for the aforementioned reasons, having a long comment about how a function works _obscures_ the code near it and makes it hard to _read_. In addition, any comments not immediately helpful to the maintainer make the _code_ harder to maintain. Now this normally isn't a problem because programmers don't actually write documentation (see most perl modules for evidence). Thus, having a small amount of documentation for each function isn't a big deal. The problem comes when you have _more_ documentation than the cursory few lines. Obviously it's great if you can keep your comments brief, but what if more explanation is needed?

Clearly someone in charge agrees with me as the existence of "__END__" demonstrates.

In reply to Re^2: POD using __END__ with function comments by zerohero
in thread POD using __END__ with function comments by zerohero

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.