super-terse summary of perl coding style conventions

git-svn-id: svn://tug.org/texlive/trunk@12318 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 80 insertions, 0 deletions

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