Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

Yes, it's another commenting node. But wait! It's constrained to a simple (?) topic which, AFAICT through super search, hasn't been discussed directly before:

Which POD commenting style do you prefer: inline POD or end-of-file POD? (examples of both below)

Personally, I'm ambivalent. (If I weren't, I wouldn't be asking for an opinion, right?)

I like inline POD because it keeps the code and docs closer together. This doesn't ensure that both get updated at the same time, but it makes updating much easier. It also helps comments directly above the subroutine not get out of sync with docs in POD.

I like end-of-file POD because all the code is in one place and the docs in another -- for many people this is easier to read.

I recently posed this question to the OpenInteract developers' mailing list but didn't get much of a response. One comment I got was that editors don't get confused as easily by EOF POD. (Yes, even (X)Emacs/CPerl gets occasionally confused by inline POD.)

If I were writing code just for me, I would use inline POD. However, I'm trying to make it easier for people to get involved with some more complicated and sizeable CPAN modules, and code readability is high on the list of impediments. However, good and consistent docs are also high on that list....

Chris
M-x auto-bs-mode

Inline POD example:

package My::Class; =pod =head1 NAME My::Class -- Does whatever I tell it =head1 SYNOPSIS my $my = My::Class->new(); my $paper = eval { $my->fetch_paper() }; if ( $@ ) { die "Sorry, could not fetch paper because of: $@"; } =head1 DESCRIPTION This class defines a multipurpose, serializable and network transportable object. =head1 METHODS =cut use strict; @My::Class::ISA = (); $My::Class::VERSION = '1.1'; =pod B<new( \%params )> (constructor) Create a new instance of this class. Initialize the object with whatever is in C<\%params>, which are not predefined.</p> Returns: new instance of this class. =cut sub new { my ( $pkg, $params ) = @_; my $class = ref $pkg || $pkg; return bless( $params, $class ); } =pod B<fetch_paper()> Retrieves paper from environment and returns it. Should be wrapped in an C<eval{}> to catch errors. Returns: L<My::Paper> object. =cut sub fetch_paper { my ( $self ) = @_; ... } 1; __END__ =pod =head1 TO DO Other operations should be added: fetch_slippers, eat_homework. =head1 BUGS Ensure that no C<My::Flea> objects are associated with object. =head1 COPYRIGHT Same as Perl. =head1 AUTHORS J. Appleseed <johnny@appleseed.com> =cut

End-of-file POD example:

package My::Class; use strict; @My::Class::ISA = (); $My::Class::VERSION = '1.1'; sub new { my ( $pkg, $params ) = @_; my $class = ref $pkg || $pkg; return bless( $params, $class ); } sub fetch_paper { my ( $self ) = @_; ... } 1; __END__ =pod =head1 NAME My::Class -- Does whatever I tell it =head1 SYNOPSIS my $my = My::Class->new(); my $paper = eval { $my->fetch_paper() }; if ( $@ ) { die "Sorry, could not fetch paper because of: $@"; } =head1 DESCRIPTION This class defines a multipurpose, serializable and network transportable object. =head1 METHODS B<new( \%params )> (constructor) Create a new instance of this class. Initialize the object with whatever is in C<\%params>, which are not predefined.</p> Returns: new instance of this class. B<fetch_paper()> Retrieves paper from environment and returns it. Should be wrapped in an C<eval{}> to catch errors. Returns: L<My::Paper> object. =head1 TO DO Other operations should be added: fetch_slippers, eat_homework. =head1 BUGS Ensure that no C<My::Flea> objects are associated with object. =head1 COPYRIGHT Same as Perl. =head1 AUTHORS J. Appleseed <johnny@appleseed.com> =cut

In reply to Inline POD vs. EOF POD by lachoy

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others rifling through the Monastery: (11)
    As of 2014-09-30 19:16 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      How do you remember the number of days in each month?











      Results (381 votes), past polls