Re: POD conventions

I prefer not to surround optional argument with brackets (or any other stuff that is typical of unix man pages) because those have real meanings in Perl. Likewise, I don't really like the pseudocode argument style of "perldoc -f" (i.e. all caps), though that's at least a sort of reference standard.

I prefer to use actual perl structures, named in a way that indicates what they should contain, and then explain them in the actual Pod description. E.g.

=head2 validate

  $is_valid = validate( \@args );

C<validate()> takes a reference to an array of arguments...
[download]

But I'll echo what the others said -- consistency is the most important thing. You'll never get everyone to agree on a form to use, but as long as you're internally consistent, you'll minimize confusion.

-xdg

Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

Comment on Re: POD conventions Select or Download Code

Replies are listed 'Best First'.
Re^2: POD conventions by cowan (Acolyte) on Mar 16, 2006 at 07:39 UTC
I agree with the "I prefer to use actual perl structures, named in a way that indicates what they should contain, ...". I would add the criteria/goal that the sample code should try to have a productivity advantage, i.e. allow cut-and-paste by the POD reader. Try to use the standard/common variable names found in the shop or application in the sample code. Examples: return code ($retcode, $rc), error return ($error_msg), etc. to make the sample code easier to quickly use.	[reply]
Re^2: POD conventions by submersible_toaster (Chaplain) on Mar 16, 2006 at 13:37 UTC
Also in agreement, \@array is far more meaningful than $arrayref or confusing []. If you are concerned about confusion (and particularly if more than one person is writing POD) - the first POD you write should be a style guide. Sounds redundant to some, but - Document how you Document, beforehand. I can't believe it's not psellchecked	[reply]