My editor has folding. I don't use it. I put the pod with the function. It's easier to maintain, and I don't find any problem doing a "find" on the function I'm interested in and hitting "next" once or twice. Or hitting the "next function" key combo. Really, it's not the issue (for most of us) that you make it out to be. Further, I strongly, strongly disagree with your statement that this makes the code harder to maintain. The code's comments (and external API) are part of the code. Separation is going to lead to disparity, which is then a bug in the code (since the docs are part of the code). To me, one of the points of intermixing POD with code is the huge convenience of colocation of code and comments making it at least plausible to keep them in sync. Which, interestingly, is also the way that Doxygen or even Javadoc. I suspect these guys know just as much about this as do the guys designing Perl when they encourage intermixing of code and documentation.

As for the existence of __END__, I'm not sure you realise that it's merely a point for the interpreter to stop and leave the file pointer in case you want to read it with the *DATA filehandle. It allows you to embed data in your source file without actually making it in your source. Many people put their POD there, but I'm not sure that's the purpose of it, merely a blessed way to use it. Personally, I think that's premature optimisation - putting it there prevents the perl parser from wasting valuable cycles looking past the POD, because it has stopped interpreting by then. But if you do things this way, then you'll never be able to use __END__ in its other manner: to provide a marker for your *DATA filehandle. If you do, then YOU will be responsible for ignoring the POD, and, personally, I'd rather that Perl's C-based interpreter skipped the POD than for me to write my own (or adapt an existing module) which can't be any faster than the native code. It's just code I don't see a need to write or maintain, just for some "convenience" (your meaning, not mine) of keeping my code easy to find.

In reply to Re^3: POD using __END__ with function comments by Tanktalus
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.