perlmeditation
lachoy
<p>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:</p>
<p>Which POD commenting style do you prefer: inline POD or end-of-file POD? (examples of both below)</p>
<p>Personally, I'm ambivalent. (If I weren't, I wouldn't be asking for an opinion, right?)</p>
<p>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.</p>
<p>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.</p>
<p>I recently posed this question to the <a
href="http://www.openinteract.org/">OpenInteract</a> 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.)</p>
<p>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 [cpan://SPOPS|complicated] and
[cpan://OpenInteract|sizeable] CPAN modules, and code readability is high on the list of impediments. However, good and consistent docs are also high on that list....</p>
<p>Chris<br>
M-x auto-bs-mode</p>
<readmore>
<p><b>Inline POD example:</b></p>
<code>
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
</code>
<p><b>End-of-file POD example:</b></p>
<code>
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
</code>