perlquestion
stephen
<P>I'm interested in what subroutine commenting practices people use. I'm not interested in figuring out which is the "best", just wonder methods others use...
<P>When I create a module, before each private subroutine I put a comment like so:
<CODE>
##
## user_address()
##
## Arguments:
## $name: string Name of the user
## $phone: string Phone num of user
##
## Returns: string Address of user
##
## Does a database check on the given user and returns
## the address.
##
sub user_address {
#whatever
}
</CODE>
<P>I always use empty parentheses on the top line, just to
make it obvious from a glance that this block of comments documents a subroutine.
<P>Also, whenever I have a subroutine that will be called from outside the module, I use POD, like so:
<CODE>
=item population()
Arguments:
$country: string Country code of country
Returns: integer Population of country
Given a country, returns the population.
=cut
sub population { ...
</CODE>
<P>My question: what do you do? I've seen a few varying styles in CPAN documentation... is there one style that you've found particularily useful, and why?
<P>
stephen
</P>