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.
True if you have docs inline with the code. Which is what I do. Yay
folding editor!
* Docs take the place of comments explaining what the routine does avoiding
duplication.
Documentation and comments serve different purposes IMO, and one can not
replace t'other. They differ in purpose because they differ in their
audience. Documentation's audience is the *user* of your code - either
the end user, or a developer wanting to use your library. Comments are
there for the maintainer of your code. Where documentation should
describe *what* the code does, comments should describe *how* it does
what it does. Comment your algorithms, comment the entry/exit
conditions of private methods etc. Comments would also cover stuff like
noting any area which you know requires particularly thorough testing to
catch any off-by-one errors and the like, or where you might want to
refactor in the future.
* Makes it easier to see that each routine has documentation.
Isn't there a module for that? ;-)
* Private docs (=begin/end private) allow you to document private and public
functions using the same style.
Ooh, I didn't know about that! What revision of perl (or rather,
perldoc) did that appear in? I think I'll stick to #comments though -
less typing!
--
David Cantrell
