Module Design and Implementation

expressed by the subroutine. For example, connect($server_address) is much 

easier to understand than socket($server_address). Avoid ambiguous verbs like 

 process  and  handle. 

An exception to the this rule are functions whose sole purpose is to return a 

particular value. In this case, dispensing with the superfluous  get  or  return  

verbs is preferable. That is, next_id() is better than get_next_id().

Try to use full words and avoid abbreviation. Some developers are under the 

impression that removing vowels from their subroutine (and module) names for 

example snd_cmd() rather than send_command() will enhance their usability. The 

time you spend typing the full name will be more than repaid by the time your 

users save remembering the name!

Capitalization is certainly a fruitful subject for flame wars, but there seems to 

be a rough consensus in the Perl community. Normal subroutines are all lowercase 

and multiple words are joined with underscores (for example, encode_html()). 

Constants and package variables are in all caps (such as FORBIDDEN and $DEBUG).

Private subroutines are preceded by an underscore (such as _parse()). Consider 

carefully before violating these expectations.

Above all, be consistent. If you're determined to use innerCaps,

7

 then at least 

do so consistently. It's far too easy to forget something like printData_filter() and 

instead type print_data_filter() or printDataFilter().

Take advantage of conventions wherever you can they reduce the time it 

takes a new user to learn to use your module. For example, if a subroutine prints to 

a file, consider using  print  or  write  in the name rather than inventing your own 

terms. You might also be able to follow the example of an existing module. If you're 

writing a CGI module that handles parameters, you might consider implementing 

a param() function that works like the CGI module's param().

Subroutine Documentation

As you plan your interface, you should document each subroutine you plan to 

write. The documentation for a subroutine should specify possible arguments and 

return values. If the subroutine will make assumptions about its arguments, then 

these should be stated. Just like the module description, a subroutine description 

should focus on what and not how. Here's a good example of a well documented 

subroutine:

7. aka StudlyCaps

75

75