-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathCODING
156 lines (115 loc) · 5.6 KB
/
CODING
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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
# TigerLily: A client for the lily CMC, written in Perl.
# Copyright (C) 1999 The TigerLily Team, <[email protected]>
# http://www.tlily.org/tigerlily/
#
# This program is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License version 2, as published
# by the Free Software Foundation; see the included file COPYING.
#
Tigerlily Coding Standards (Such as they are)
--------------------------
After yet another debate over indent width, we decided to write up
some basic coding standards for tlily. Feel free to add to this as
you see fit. Not all of our code will fully adhere, but it probably
should eventually. Feel free to help out with cleaning things up..
-------------------------------------------------------------------------------
1) Memory usage
Tigerlily is a memory hog. It always will be. However, we do have a
few things to say on how to avoid making it trully horrendous:
- When possible, import just the symbols you need from a module.
For example, let's say you wanted the POSIX "tolower" function.
A "use POSIX" adds 1224k to perl on solaris sparc. If you do a
"use POSIX qw(tolower);" will save you 300k.
- Which brings us to.. POSIX.pm is a hog, even if you do
selectively import symbols. Try to avoid it if you can. In the
above example, perl's lc() would be a much better choice :)
- The IO:: modules are also memory hogs, and slow to boot. If you
want a filehandle with a restricted scope, try something like this:
local *FH;
open(FH, "foo");
$self->{fh} = \*FH;
For more information on filehandles, look at this handy tutorial:
http://language.perl.com/misc/fmindir
- If you want to check the comparative memory usage of tlily with
and without a module, try something like this:
perl -MIO::Handle -e 'system("ps auxww | grep $$")';
-------------------------------------------------------------------------------
2) Namespace pollution
It is very rude for a module to stick symbols into the namespace of its
callers. Don't use @EXPORT; use @EXPORT_OK instead.
Don't attempt to create your own namespace with prefixes to symbol names.
Instead of event_raise, consider Event::raise. Perl has a perfectly good
namespace mechanism. Use it. :>
-------------------------------------------------------------------------------
3) Bracing
This is the bracing style we want to use:
if ($foo == 1) {
do_some_stuff
. . .
} else {
do_some_other_stuff
. . .
}
Variations on this theme are fine... examples:
if ($foo == 1) { call_a_function(); }
call_a_function() if ($foo == 1);
What I don't want to see is:
if ($foo == 1)
{
. . .
}
This style wastes space. I will mercilessly reformat code that I see
that uses this.
-------------------------------------------------------------------------------
4) Indenting
We have decided to use 4 space indents. This means 4 spaces.
Don't change your tab stops no matter what. A tab is 8 spaces.
Emacs will indent the code correctly if you use cperl-mode (perl-mode
is probably more or less ok as well, but we recommend cperl-mode)
To make emacs use a 4 space indent in cperl mode, put the following in
your ~/.emacs file:
(setq cperl-indent-level 4)
-------------------------------------------------------------------------------
5) Prototypes
Perl permits you to define functions with prototypes (for example, sub
foo($) defines foo to take a single scalar argument). Perl function
prototyping is not, however, intended to act in any way like C function
prototyping. It exists to permit the creation of functions which act
like Perl builtin functions, rather than to provide argument checking.
Do not use function prototypes unless you have a clear understanding
of what they are for and why you want them. If you think you want
prototypes on all your functions, you are probably wrong.
See perlsub(1) for more information on prototypes.
-------------------------------------------------------------------------------
6) Help text
Every user command you register should have both a short description
(shelp_r) and a help page (help_r) associated with it. Help pages
for commands should follow this form:
| help_r("command" => "
| Usage: %command options
| %command other options
|
| Description of how to use the command, possibly spanning \
| multiple lines.
|
| (see also %othercommand)
| ";
Note that you should not word wrap paragraphs which span more than one line:
the UI is quite capable of doing this for you, and will get it right on
different screen widths. You may wish to separate lines with a \\n (as
above) to keep things nice and tidy in your code.
On the same note, the help manager will automatically remove any unneeded
newlines from the start and end of your help text, so feel free to add some
if it makes things look nicer for you. (Again, see above.)
-------------------------------------------------------------------------------
7) Object data
UI and server objects are hashrefs. Occasionally, an extension author may
want to stick a bit of private data into one of these objects. This is
permitted. Extension-private hash keys should begin with "_", and care
must be taken for different extensions to not accidentally use the same
key.
Several UIs may share a single input line. If you want to store data
relating to the input line, put it in $ui->{input}.
-------------------------------------------------------------------------------
8) Other
There's plenty of room for more stuff in here.. Go for it :)