Re: Preferred method of documentation?

in reply to Preferred method of documentation?

This is an example of a well documented method:

=head2 insertRows($nameTable, $raRow)

Insert the data in $raRow (array ref with hash refs (key:
field name, value: field data) into $nameTable.

Return 1 on success, else 0. Die on fatal errors.

=cut
sub insertRows { my $self = shift;
    my ($nameTable, $raRow) = @_;
[download]

It describes the interface to the method. So you don't have to read the code to know how to use it. But you need to keep it in sync with the implementation, so the POD should be next to the method (Locality breeds Maintainability).

If you write the interface description before you start coding the method, chances are that you'll think one more time about edge cases, error conditions and stuff like that. Personally I find that a very useful way of organizing my thoughts before diving in.

Names of classes, variables, and methods should be meaningful and consistent. That way you don't need so many comments. Try to avoid abbreviations.

I find it useful to include the "domain specific data type" in the variable name to indicate what it contains, especially when using dynamically typed languages.

$timeout    vs $secondsTimeout
$table      vs $nameTable
$workspace  vs $dirWorkspace
[download]

When you do comment, note the why, not the what. Write down assumptions, thoughts and non-obvious design decisions.

Having said that, it is ok to say what a regexp does, because it's often not obvious. It's useful to provide a sample of what you're trying to match. Alway use /x to make it more readable.

If you look at CPAN, each module has a SYNOPSIS section with short examples. These are very powerful.

Apart from all other benefits with unit tests, they also provide great hands-on documentation, like a SYNOPSIS on steroids.

Comment on Re: Preferred method of documentation? Select or Download Code

Replies are listed 'Best First'.
Re^2: Preferred method of documentation? by radiantmatrix (Parson) on Oct 06, 2004 at 15:38 UTC
I most wholeheartedly agree with the parent. I'd like to add, however, that a POD section granting an overview of the module is most helpful as well. Poke around on the CPAN docs -- many of the modules there are well-documented. Combine that style with that of jplindstrom above, and you have superb documentation that is both in-code and extractable using any one of the `pod2` tools. The existence of `pod2html` also means that your documentation will be intranet-publishable, which looks great to your project manager. radiantmatrix `require General::Disclaimer;`	[reply]

Replies are listed 'Best First'.

Re^2: Preferred method of documentation?
by radiantmatrix (Parson) on Oct 06, 2004 at 15:38 UTC

I most wholeheartedly agree with the parent. I'd like to add, however, that a POD section granting an overview of the module is most helpful as well.

Poke around on the CPAN docs -- many of the modules there are well-documented. Combine that style with that of jplindstrom above, and you have superb documentation that is both in-code and extractable using any one of the pod2 tools.

The existence of pod2html also means that your documentation will be intranet-publishable, which looks great to your project manager.

radiantmatrix
require General::Disclaimer;

[reply]

In Section Meditations