$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. * Indent by two spaces and put the function-opening { in column 1 (as above), 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 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 onyl 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 yet again. Documentation: http://search.cpan.org/~ferreira/Exporter-5.63/lib/Exporter.pm