Module Design and Implementation

my $checker = MailChecker >new(imap_sever => $imap_server,

                               username   => $username,

                               password   => $password);

$checker >check();

Now new() can be written to require the parameters that don't have sensible defaults. 

This demonstrates an important goal of OO design your classes should make it 

impossible to put an object in an  illegal  state that can only cause problems later.

Method Documentation

Methods need much the same documentation as normal subroutines return 

values, parameters, and error handling all need coverage. However, method docu 

mentation also needs to cover how the method affects the object it is called on. If 

a method has side effects on the object, then these need to be spelled out. For 

example, BOA::Network's send() method keeps statistics about how many bytes 

have been written and network speed. The documentation for this method would 

look like this:

=over 4

=item $success = $net >send($msg)

The send() method sends $msg along the network connection.  Returns true if

the send succeeded, false if the send failed.  Error details can be

retrieved using the error() method after a failure occurs.  This method

updates the read_bytes and kps attributes.

=back

If a method has no effect on the object, then this should be documented too. 

Methods that do not effect the state of the object are called constant methods in 

the OO texts. Perl doesn't have any syntax for enforcing constant methods, but 

documenting them can give your users valuable information.

Accessor Mutators

Accessor mutators are the bread and butter of object oriented programming. The 

ability to examine and change the state of an object is the most basic service that 

85

85