Re: Rules of Proper Perl Style

Keeping in tune with the Mythical Man-Month (a terrific book, might I add)...

Documentation for code is imperative when there will be other people using, maintaining, or trying to understand your programs.

This is not to say you must describe every action you take:

# set $foo to 'bar'
my $foo = "bar";

# send $foo to this_func()
this_func($foo);
[download]

but rather, try to make your code self-documenting, and leave the API and verbose explanation for the Pod:

my $prog_state = "bar";
execInstructions($prog_state);

# and later...

=item C<execInstructions($state)>

Executes a given set of instructions for a specific state that the pro
+gram is in.  Blah blah blah.
[download]

Use well-tested algorithms, and note where evidence on their effectiveness can be found:

# radix sort, O(Nk)
# "Mastering Algorithms in Perl", Orwant, et. al.

my @sorted_names = radixSort(\@names);
[download]

If you use your own algorithms, provide explanation for them -- not in the code directly, but perhaps in the Pod:

# find_missing() uses a binary-tree approach
# see IMPLEMENTATION section of Pod for details

my $next_ID = find_missing(\@list);
[download]

If you use idiomatic Perl, provide some insight as to what it's doing.
```
perl -pe '$_ x= --$|' FILE
[download]
```
If you pass that one-liner off on a newsgroup or mailing list as a means to print every other line in a file, give the readers the common decency of a brief explanation:
The x operator is the "count" or "repetition" operator. Saying $_ x= $foo means $_ = $_ x $foo -- it's basically string multiplication. And we use --$| here because it's magical; if it's 0, subtracting one makes it -1, which is a true value, and it stores it as 1; then, when we subtract one, it's 0.

japhy -- Perl and Regex Hacker

Comment on Re: Rules of Proper Perl Style Select or Download Code

Replies are listed 'Best First'.
(dws)Re: Re: Rules of Proper Perl Style by dws (Chancellor) on Feb 18, 2001 at 03:43 UTC
Much as I like Mythical Man Month, I think Brook's admonition on the necessity of code documentation is dated, and should be read as a statement about coding practices of that bygone era, when it was much more difficult to write code that could stand on its own without additional documentation than it is today. At the time the book was written, most compilers (with the exception of COBOL) limited variable names to six or eight characters. It was hard to write code that clearly expresses its intent given that constraint. A reader needed additional commentary and documentation to help untangle cryptic fragments. Contemporary methodologies (the Extreme Programming folks in particular) eschew commentary, and use the need for commentary as a hint that a piece of code needs to be refactored or rewritten. I don't agree with them entirely on this, but they do have a good point. I'm not arguing that code needs no documentation. High-level overviews are always welcome. But we now have better tools than Brooks did when he was working on OS/360, and can use those tools to write more descriptive code than those in Brooks's era could. The trick, of course, is to do so.	[reply]

Replies are listed 'Best First'.

(dws)Re: Re: Rules of Proper Perl Style
by dws (Chancellor) on Feb 18, 2001 at 03:43 UTC

Mythical Man Month,

At the time the book was written, most compilers (with the exception of COBOL) limited variable names to six or eight characters. It was hard to write code that clearly expresses its intent given that constraint. A reader needed additional commentary and documentation to help untangle cryptic fragments.

Contemporary methodologies (the Extreme Programming folks in particular) eschew commentary, and use the need for commentary as a hint that a piece of code needs to be refactored or rewritten. I don't agree with them entirely on this, but they do have a good point.

I'm not arguing that code needs no documentation. High-level overviews are always welcome. But we now have better tools than Brooks did when he was working on OS/360, and can use those tools to write more descriptive code than those in Brooks's era could. The trick, of course, is to do so.

[reply]