summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-03-05 19:56:54 +0000
committerKarl Berry <karl@freefriends.org>2009-03-05 19:56:54 +0000
commit5086aca10a9a84258b51784513eb03365e10d2ea (patch)
tree8ab98d2a75ddaebbdfb848243a84471c60209341
parent36f6715604625a3e362534859befd7f94e2f4414 (diff)
super-terse summary of perl coding style conventions
git-svn-id: svn://tug.org/texlive/trunk@12318 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r--Master/tlpkg/doc/coding-style.txt80
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.
+
+