Michael G Schwern wrote:
On Fri, Aug 05, 2005 at 11:32:45AM -0400, Robert wrote:
Is the inline POD the current preferred way?
That really depends on who you ask. Me? I prefer it. Its totally a matter
of style.
Pros:
* Keeps the docs close to the code so you're more likely to keep the docs up
to date.
* Docs take the place of comments explaining what the routine does avoiding
duplication.
* Makes you more likely to read and use the documentation causing it to get
more maintenance attention.
* Makes it easier to see that each routine has documentation.
* Private docs (=begin/end private) allow you to document private and public
functions using the same style.
I'll let someone else in the other camp write the cons.
I've tried both approaches and I'm not a complete fanatic of either,
although recently I've been leaning more towards "comments after
__END__". I'd say that the cons of the inline approach are:
* The code gets "lost" among the documentation, as often you have more
documentation than code. Syntax highlighting reduces the problem, but
the POD still takes half the screen if you have short subs.
* The code has to be in the same order as the documentation, which
sometimes is a hindrance.
Curiously, I've found that I like the inline approach on my modules,
because of "Keeps the docs close to the code so you're more likely to
keep the docs up to date", but I hate the inline POD when I'm trying to
figure out how someone else's code works, because the POD just gets in
the way. That's why now I'm putting the POD at the bottom: "Do unto
others as you would have them do unto you".
Another option would be to dust the code folding features of my editor
and see if they work for hiding inline POD temporarily.
Ivan
