summaryrefslogtreecommitdiff
path: root/Master/tlpkg/doc/coding-style.txt
blob: 6a98ecc77a8dd09d845177112f9e0500c4d55a64 (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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
$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