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. The most common misconception about inline POD is that it slows compilation or takes more memory. This is not true as perl can detect POD as simply (or simpler) than it can a comment. And you don't worry about your comments slowing down code. Extensive benchmarking has borne this out. POD is not stored by perl any more than a comment is so it adds no extra memory bloat. -- Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern 'All anyone gets in a mirror is themselves,' she said. 'But what you gets in a good gumbo is everything.' -- "Witches Abroad" by Terry Prachett
