$Id$
Public domain.

This is all trying to record our general conventions, not absolute
rules.  Aside from personal preferences, sometimes exceptions are necessary.


* In general it's best to start scripts #!/usr/bin/env perl.


* Start the code with the various require and use statements,
our variables, etc., and then:

exit (&main ());

sub main {
  ...
  return 0;
}

This avoids the temptation to put an ever-growing amount of code at the
top level.  It is better to have the top-level code inside a subroutine.


* The Perl "unless" keyword is cute but mind-bending.  Use "if !" instead.


* Use "/" as the delimiter of first choice for regular expressions.  When
the regex includes a /, use ",".  When it includes both "/" and ",", use "!".


* In the absence of prototypes, try to order routines in a given file
top-down rather than bottom-up.  So main would come first.


* Normal indentation is two spaces per level.
Put a space between arguments of function calls.
Karl puts a space before the ( of function calls but no one else does :).


* Handle subroutine arguments like this:

sub foo {
  my ($arg1,$arg2,@rest) = @_;
  ...
}

Use this in preference to `shift' even when there is only one argument.
It takes up only one line, which is good.  And if the number of
arguments to the function later changes, text changes are minimized.


* It looks strange to write hash keys as if they were keywords (although
it is certainly common Perl practice to do so).  Instead, write them as
strings:
    my $foo = $h->{"key"};
for a reminder that these are not keywords or subroutine names.

OTOH, no need to go so far as to use escaped quotes in already-quoted
contexts such as
  print "foo is $h->{key}\n";
Perl does the right thing here without painful \" constructs, so take
advantage of it.


* In the absence of prototypes, consider writing &foo() instead of foo()
for user-defined subroutine calls, also to be a reminder that these are
not Perl keywords.


* Similarly, Perl lets you omit parentheses around function calls and/or
primitives in many situations.  As a rule, don't do this.  It is far
clearer to use parens when there's a function call.  Exceptions for
these primitives: exists, defined, print and its relatives.


* The above is essentially the recommendation of the GNU coding standards
for C (http://gnu.org/prep/standards).  The one exception is the
standards' recommendation of putting braces on lines by themselves, thus
eating up precious vertical space.  Do not do that.


* Exporting symbols and keeping namespaces clean:

In general, the only things which should be in @EXPORT are those
which are needed nearly universally, such as debug and log.  Barewords
like somefunc are preferable to prefixed &somefunc.

In contrast, EXPORT_OK should list all the "public" symbols (but not
private ones) of a module.  It is good to list them in the same order as
they are defined in the file, since that both makes it obvious where a
new symbol should be added, and provides a sort of check that all and
only the right symbols are there.  The EXPORT symbols need not and
should not be listed again in EXPORT_OK.

Then, use TeXLive::SomeModule;
will import all the EXPORT (but not EXPORT_OK) symbols.

If you need to import a few EXPORT_OK's in addition to the EXPORT's
use TeXLive::SomeModule (:DEFAULT oksym1 oksym2);
instead of redundantly listing the @EXPORT symbols.

If you only use a symbol once or twice, don't import it at all.  Just
use TeXLive::SomeModule::somesym.  This has the advantage that someone
reading the source will know immediately where it comes from, and that
it's not local.  This is especially useful with $variables, which our
brains tend to think of as "local".

If you want to import every single EXPORT_OK symbol,
use TeXLive::SomeModule (/./);
should do it (I've never actually tried it).  This is certainly far
better than explicitly listing every symbol again.

Documentation:
http://search.cpan.org/~ferreira/Exporter-5.63/lib/Exporter.pm