From 5086aca10a9a84258b51784513eb03365e10d2ea Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 5 Mar 2009 19:56:54 +0000 Subject: super-terse summary of perl coding style conventions git-svn-id: svn://tug.org/texlive/trunk@12318 c570f23f-e606-0410-a88d-b1316a301751 --- Master/tlpkg/doc/coding-style.txt | 80 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 Master/tlpkg/doc/coding-style.txt diff --git a/Master/tlpkg/doc/coding-style.txt b/Master/tlpkg/doc/coding-style.txt new file mode 100644 index 00000000000..a6aac4a7211 --- /dev/null +++ b/Master/tlpkg/doc/coding-style.txt @@ -0,0 +1,80 @@ +$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. + + +* 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 :). + + +* The Perl "unless" keyword is cute but mind-bending. Use "if !" instead. + + +* Handle subroutine arguments like this: + +sub foo +{ + my ($arg1,$arg2,@rest) = @_; + ... +} + +Always use this, vs. 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 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. + + -- cgit v1.2.3