Chapter 3

=over

=item @msgs  = check_mail($imap_server, $username, $password)

=item @msgs  = check_mail($imap_server, $username, $password, $mailbox)

This routine checks for new mail on a IMAP server.  It takes three required

arguments   the server address (name or IP), the user name and the

password.  The fourth, optional, argument is the mailbox name,

which will default to "INBOX" if not set.  If an error is encountered  1 is

returned and an error message is printed to STDERR.  If successful, a list of

new message IDs is returned that can be used with retrieve_mail().  An empty

list indicates no new messages.

=back

Notice that an example is given for each possible call to the function both with 

the optional $mailbox argument and without. This is a common convention that is 

worth following. Another possibility is to place the optional argument in square 

brackets (for example, [$mailbox]), but that risks confusion with a reference to an 

array containing the argument.

One common problem with subroutine documentation is ambiguous language. 

For example,  the subroutine may return undef on failure.  The reader is left 

wondering what else it might do on failure. There are two crucial pieces of infor 

mation that a user needs how to check for an error and how to determine what 

the error was. Certainly there's more than one way to do it just make sure you 

document which one you choose!

Parameter Passing

Simple subroutines are best served by simple interfaces. If you have only a couple 

parameters, then there's no good reason to do anything more complicated than 

take them directly from @_. However, when designing a subroutine that will take 

more parameters, you should consider using a named parameter style. Here's a 

call to the check_mail() subroutine described earlier, redesigned to use a named 

parameter style:

check_mail(imap_server => $imap_server,

           username    => $username,

           password    => $password);

76