summaryrefslogtreecommitdiff
path: root/Master/tlpkg/doc/coding-style.txt
blob: a6aac4a7211cb77c7036f61d63c668041bcae6fe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
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.