I personally will always only put POD in the __END__ of packages and scripts
Yes.
In a module, I use POD (after __END__) for the user of the module and write comments (with the code) for the maintainer of the module.
That is, I like to keep user and maintainer documentation separate.
See also:
| [reply]
[d/l] |
POD inside the sub though is incredibly jarring to me.
Amen.
| [reply] |
Agree that POD is a million times better than # Comments. POD inside the sub though is incredibly jarring to me. I don't even like it between subs. I like to wear one hat at a time and code and documentation are polar opposites to my creative flow and focus.
I agree that embedding POD in subs is somewhat jarring (ugly) and sympathize with the desire to wear one hat at a time (because I too love to code, but hate writing documentation ;). I embed POD in subs to force myself to keep the code and docs in sync. Since they are adjacent to each other this chore becomes very convenient. I used to code first and document later but found it annoying having to decipher non-obvious code all over again resulting in vague documentation. I tend to understand the code perfectly when it's being written and find that to be the perfect time to write accurate documentation. Another benefit to this technique allows one to construct a built-in help system that can display the POD of a specific sub with an option to also dump the code for easy review.
| [reply] |
Oh, I understand the reasons and even agree in principle—that current docs are more important than some concerns and having them in your face is a reminder to keep them current. And I'd much rather see POD somewhere than no POD. And a code/POD dumper is an interesting idea. So many "and"s. Still I don't think—for most people, I don't hard prescribe or proscribe, only try to find best practices—it prevents more trouble than it causes. If there is no inline POD, I can have 2 or maybe even 10 or 15 subs in the terminal at once. When I'm debugging or trying to think straight, that is much more valuable for cognitive load; yes, I suppose some IDEs can hide/show POD/comments and I don't doubt LanX will have an emacs macro for perl-mode.tt to do it after reading this :P but still. And sometimes you're stuck on a remote terminal you have no control over or on an IDE you don't know. Additionally—so many "and"s are horrible style but don't let my bad style get in the way of my preaching about style, uhmmmm…—many, probably the lion's share of devs won't update or write the POD regardless of where it is. Like the car manual analogy, consider the footnote; publishers having centuries of accumulated practices in presenting written information. Inline footnotes would be awful. Even the bottom of the same page is slightly controversial with some publishers opting to put them at the end of the complete text; I find this similar to POD after the __END__ (as the bottom of multiple pages/modules) or in a completely new .pod file; external to the code/text.
An advantage of completely separate code and docs is you can trivially ship or build without docs if you want. Of course with PPI and such you can strip it no matter where it is. So… viva Perl.
| [reply] |
