• -w while testing.
• use strict; if more than 10 lines.
• Minimize file scope variables.
• Avoid subs that have more than 40 lines of code, keep it to 25 if you can.
• Use verbs for subroutines, use nouns for variables, be descriptive and consistent.
• Leave behind clear code, use parens on subs, use arrows to dereference rather than shortcuts, comment on behavior and logic rather than flow, beware hidden behavior and void context magic.

Hidden behavoir like non-obvious return values can eat you alive. I try and avoid subs that both modify a parameter handed to them and return a real value. I try to use return $blah; so that people don't add a print at the end of my sub and suddenly it ALWAYS returns a "1". =)

--
$you = new YOU;
honk() if $you->love(perl)

extremely writes:

Rule 1, don't call them rules. =) Guidelines is a much better term.

Amen! TMTOWTDI, for just about any vaule of "It."

I'll add a plug for my favorite short read on writing literate Perl here. Some of you might recognize the author.
:-)

And as for adding guidelines:

• Comment your data structures,
• And use good, long, descriptive variable names.

Bonus points for anyone who can remember who it was that said "show me your data structures, and I don't need to see your algorithms..." or something like that.

Peace,
-McD

That'd be Fred Brooks. The exact quote is

"Show me your code and conceal your data structures, and I shall continue to be mystified. Show me your data structures, and I won't usually need your code; it'll be obvious."

Kinda hard to believe now, but back in the days when we had to shovel coal to power our mammoth steam-belching, card fed computers, procedural code was the order of the day. The idea of organizing code around "data structures" was a strange one.

Frederick P. Brooks's -- The Mythical Man-Month
"Show me your flowcharts and conceal your tables, and I'll continue to be mystified. Show me your tables, and I won't usually need your flowcharts; they'll be obvious."

Oddly enought, the "short read on writing literate Perl here", mentioned at the start of this thread, includes the following:

     "Rob Pike says: `Data dominates. If you've chosen the right
      data structures and organized things well, the algorithms
      will almost always be self-evident.  Data structures, not
      algorithms, are central to programming. (See Brooks p. 102.)'"

We all seem to be dipping our toes in the same stream :-)

p
update: That "toes in stream" was the best I could come up with at that moment.
shoulda/coulda been: "Which only goes to prove the point."

Using -w flag is always good too.. shows the warnings..

• 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.

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.

1. Do not use $_ (implicitly), use named variables.
Reason : You need to keep track of where the value of $_ is created, and where it is destroyed, which is difficult. You also need to keep track of what functions use $_, and as what argument.

2. Do not use consecutive maps and/or greps on a line. Split them into several lines with temporary variables, or use foreach.
Reason: Hard to look into maps and greps with a debugger.

3. Write long variable and function names, as "jump_to_good_place_in_file()",

    my $current_template_contents = $self->current_template_contents;
[download]

(OK, I write almost ridiculously long names, but it works for me :-)

4. Write methods that are no longer than one screen. If longer, make it into two methods.

5. Use objects and methods instead of subroutines. Objects give a spatial relationship between chunks of code, which is easier for the (average) mind to grasp than several subroutines called at diiferent places in a program.

6. Write a lot of comments, especially about the purpose of a code chunk.

/jeorgen

6. Write a lot of comments, especially about the purpose of a code chunk.

Time for me to beat my "comments" drum again.

Ideally comments should not explain the purpose of a code block. The purpose should be self-evident. Moving your code out to a well named method/sub can often help greatly with this.

Instead, comments should explain the WHY behind the particular manner in which you achieve your purpose. Any average programmer should be able to read your code and see easily enough what it does. But even a great programmer might have difficult knowning why you did it a certain way. That's where good comments save a lot of head-scratching.

Tony

Tony