A question of Style, was: SPUG: Sort an array question

[Jerome O'Neil]

On Sat, Dec 28, 2002 at 04:06:04PM -0800, Michael R. Wolf wrote:
> > And what about POD? I'm surprised at how many Perl programmers I meet
> > who don't know anything about POD (maybe I should volunteer to give a
> > lightning talk on my favorite ways to use POD).
> 
> I for one would like that.  I know what POD *is*, have even used it on
> occasion, but it would sure do me good to see some other's "favorite
> ways".  Just like this current discussion is airing folks' accumulated
> *practical* knowledge of _Perl_ style, you could focus us on the
> *practical* knowledge of _POD_ style.  

I've followed the folowing conventions for the last three years, and it
works well for me.  More importantly, it works well for the people that
read and maintain my code droppings.  

I can't control how the thing will be maintained in the future, but I can
at least facilitate easy maintenence.  I've found that older versions
of my stuff continue to be documented in a similar fashion, which means the
anonymous maintainers are at least using the tools.  It also produces an
attractive API document that is usefull for demonstrating progress to your
boss, or any other "don't write code" types that might have an interest.

This is good.

-Jerome

package Foo::Bar;

=pod

=head1 NAME Foo::Bar

A brief synopsis of Foo::Bar

=head1 SYNOPSIS

 my $foo = new Foo::Bar;
 $foo->bar();
 $foo->baz();
 
=head 1 METHODS

=over 4

=item $foo->bar();

Ddescribe my method.

=cut

sub bar { 
 # bar bar bar bar
}

=pod

=item $foo->baz();

Describe my method

=cut

sub baz{
 # baz baz baz
}

"The times, they are a changin'";

__END__

=back

=head1 HISTORY

 $Author: $

 $Log: $



-- 
Jerome O'Neil
Sr Software Engineer
Cobalt Professional Services
206-219-8008

If it's automotive and it's internet, it's Cobalt.

 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     POST TO: spug-list at pm.org       PROBLEMS: owner-spug-list at pm.org
      Subscriptions; Email to majordomo at pm.org:  ACTION  LIST  EMAIL
  Replace ACTION by subscribe or unsubscribe, EMAIL by your Email-address
 For daily traffic, use spug-list for LIST ;  for weekly, spug-list-digest
     Seattle Perl Users Group (SPUG) Home Page: http://seattleperl.org