← Back to branch summary

~ubuntu-branches/ubuntu/warty/libapache2-mod-perl2/warty

« back to all changes in this revision

Viewing changes to docs/devel/core/coding_style.pod

  • Committer: Bazaar Package Importer
  • Author(s): Andres Salomon
  • Date: 2004-02-13 22:22:35 UTC
  • Revision ID: james.westby@ubuntu.com-20040213222235-x0ggyscn50jvab2v
Tags: upstream-1.99.12
Import upstream version 1.99.12

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/devel/core/coding_style.pod
 
1
=head1 NAME
 
2
 
 
3
mod_perl Coding Style Guide
 
4
 
 
5
=head1 Description
 
6
 
 
7
This document explains the coding style used in the core mod_perl
 
8
development and which should be followed by all core developers.
 
9
 
 
10
=head1 Coding Style Guide
 
11
 
 
12
We try hard to code mod_perl using an identical style. Because
 
13
everyone in the team should be able to read and understand the code as
 
14
quickly and easily as possible. Some will have to adjust their habits
 
15
for the benefit of all.
 
16
 
 
17
=over 4
 
18
 
 
19
=item * C code
 
20
 
 
21
mod_perl's C code follows the Apache style guide:
 
22
http://dev.apache.org/styleguide.html
 
23
 
 
24
=item * XS code
 
25
 
 
26
C code inside XS modules also follows the Apache style guide.
 
27
 
 
28
=item * Perl code
 
29
 
 
30
mod_perl's Perl code also follows the Apache style guide, in terms of
 
31
indentation, braces, etc. Style issues not covered by Apache style of
 
32
guide should be looked up in the I<perlstyle> manpage.
 
33
 
 
34
=back
 
35
 
 
36
Here are the rough guidelines with more stress on the Perl coding
 
37
style.
 
38
 
 
39
=over 4
 
40
 
 
41
=item Indentation and Tabs
 
42
 
 
43
Do use 4 characters indentation.
 
44
 
 
45
Do NOT use tabs.
 
46
 
 
47
Here is how to setup your editor to do the right thing:
 
48
 
 
49
=over
 
50
 
 
51
=item * x?emacs: cperl-mode
 
52
 
 
53
  .xemacs/custom.el:
 
54
  ------------------
 
55
  (custom-set-variables
 
56
     '(cperl-indent-level 4)
 
57
     '(cperl-continued-statement-offset 4)
 
58
     '(cperl-tab-always-indent t)
 
59
     '(indent-tabs-mode nil)
 
60
  )
 
61
 
 
62
=item * vim
 
63
 
 
64
  .vimrc:
 
65
  -------
 
66
  set expandtab " replaces any tab keypress with the appropriate number of spaces
 
67
  set tabstop=4 " sets tabs to 4 spaces
 
68
 
 
69
=back
 
70
 
 
71
 
 
72
=item Block Braces
 
73
 
 
74
Do use a style similar to K&R style, not the same. The following
 
75
example is the best guide:
 
76
 
 
77
Do:
 
78
 
 
79
   sub foo {
 
80
       my($self, $cond, $baz, $taz) = @_;
 
81
  
 
82
       if ($cond) {
 
83
           bar();
 
84
       }
 
85
       else {
 
86
           $self->foo("one", 2, "...");
 
87
       }
 
88
  
 
89
       return $self;
 
90
   }
 
91
 
 
92
Don't:
 
93
 
 
94
   sub foo
 
95
   {
 
96
       my ($self,$bar,$baz,$taz)=@_;
 
97
       if( $cond )
 
98
       {
 
99
           &bar();
 
100
       } else { $self->foo ("one",2,"..."); }
 
101
       return $self;
 
102
   }
 
103
 
 
104
=item Lists and Arrays
 
105
 
 
106
Whenever you create a list or an array, always add a comma after the
 
107
last item. The reason for doing this is that it's highly probable that
 
108
new items will be appended to the end of the list in the future. If
 
109
the comma is missing and this isn't noticed, there will be an error.
 
110
 
 
111
Do:
 
112
 
 
113
  my @list = (
 
114
      "item1",
 
115
      "item2",
 
116
      "item3",
 
117
  );
 
118
 
 
119
 
 
120
Don't:
 
121
 
 
122
  my @list = (
 
123
      "item1",
 
124
      "item2",
 
125
      "item3"
 
126
  );
 
127
 
 
128
=item Last Statement in the Block
 
129
 
 
130
The same goes for C<;> in the last statement of the block. Almost
 
131
always add it even if it's not required, so when you add a new
 
132
statement you don't have to remember to add C<;> on a previous line.
 
133
 
 
134
Do:
 
135
 
 
136
  sub foo {
 
137
      statement1;
 
138
      statement2;
 
139
      statement3;
 
140
  }
 
141
 
 
142
Don't:
 
143
 
 
144
  sub foo {
 
145
      statement1;
 
146
      statement2;
 
147
      statement3
 
148
  }
 
149
 
 
150
=back
 
151
 
 
152
 
 
153
 
 
154
=head1 Function and Variable Prefixes Convention
 
155
 
 
156
=over 4
 
157
 
 
158
=item modperl_
 
159
 
 
160
The prefix for mod_perl C API functions.
 
161
 
 
162
=item MP_
 
163
 
 
164
The prefix for mod_perl C macros.
 
165
 
 
166
=item mpxs_
 
167
 
 
168
The prefix for mod_perl XS utility functions.
 
169
 
 
170
=item mp_xs_
 
171
 
 
172
The prefix for mod_perl I<generated> XS utility functions.
 
173
 
 
174
=item MPXS_
 
175
 
 
176
The prefix for mod_perl XSUBs with an XS() prototype.
 
177
 
 
178
=back
 
179
 
 
180
 
 
181
 
 
182
 
 
183
 
 
184
 
 
185
 
 
186
=head1 Coding Guidelines
 
187
 
 
188
The following are the Perl coding guidelines:
 
189
 
 
190
 
 
191
=head2 Global Variables
 
192
 
 
193
=over 4
 
194
 
 
195
=item avoid globals in general
 
196
 
 
197
=item avoid $&, $', $`
 
198
 
 
199
See C<Devel::SawAmpersand>'s I<README> that explains the evilness.
 
200
Under mod_perl everybody suffers when one is seen anywhere since the
 
201
interpreter is never shutdown.
 
202
 
 
203
=back
 
204
 
 
205
 
 
206
=head2 Modules
 
207
 
 
208
=over 4
 
209
 
 
210
=item Exporting/Importing
 
211
 
 
212
Avoid too much exporting/importing (glob aliases eat up memory)
 
213
 
 
214
When you do wish to import from a module try to use an explicit list or
 
215
tag whenever possible, e.g.:
 
216
 
 
217
  use POSIX qw(strftime);
 
218
 
 
219
When you do not wish to import from a module, always use an empty list
 
220
to avoid any import, e.g.:
 
221
 
 
222
  use IO::File ();
 
223
 
 
224
(explain how to use Apache::Status to find imported/exported
 
225
functions)
 
226
 
 
227
=back
 
228
 
 
229
 
 
230
=head2 Methods
 
231
 
 
232
=over 4
 
233
 
 
234
=item indirect vs direct method calls
 
235
 
 
236
Avoid indirect method calls, e.g.
 
237
 
 
238
Do:
 
239
 
 
240
  CGI::Cookie->new
 
241
 
 
242
Don't:
 
243
 
 
244
  new CGI::Cookie
 
245
 
 
246
=back
 
247
 
 
248
 
 
249
 
 
250
 
 
251
=head2 Inheritance
 
252
 
 
253
=over 4
 
254
 
 
255
=item Avoid inheriting from certain modules
 
256
 
 
257
Exporter.
 
258
To avoid inheriting B<AutoLoader::AUTOLOAD>
 
259
 
 
260
Do:
 
261
 
 
262
  *import = \&Exporter::import;
 
263
 
 
264
Don't:
 
265
 
 
266
  @MyClass::ISA = qw(Exporter);
 
267
 
 
268
=back
 
269
 
 
270
 
 
271
 
 
272
 
 
273
 
 
274
=head2 Symbol tables
 
275
 
 
276
=over 4
 
277
 
 
278
=item %main::
 
279
 
 
280
stay away from C<main::> to avoid namespace clashes
 
281
 
 
282
=back
 
283
 
 
284
=head2 Use of $_ in loops
 
285
 
 
286
Avoid using C<$_> in loops unless it's a short loop and you don't call
 
287
any subs from within the loop. If the loop started as short and then
 
288
started to grow make sure to remove the use of C<$_>:
 
289
 
 
290
Do:
 
291
 
 
292
  for my $idx (1..100) {
 
293
      ....more than few lines...
 
294
      foo($idx);
 
295
      ....
 
296
  }
 
297
 
 
298
Don't:
 
299
 
 
300
   for (1..100) {
 
301
       ....more than a few statements...
 
302
       foo();
 
303
       ....
 
304
   }
 
305
 
 
306
Because foo() might change C<$_> if foo()'s author didn't localize C<$_>.
 
307
 
 
308
This is OK:
 
309
 
 
310
   for (1..100) {
 
311
       .... a few statements with no subs called
 
312
       # do something with $_
 
313
       ....
 
314
   }
 
315
 
 
316
 
 
317
 
 
318
 
 
319
 
 
320
=head1 Maintainers
 
321
 
 
322
Maintainer is the person(s) you should contact with updates,
 
323
corrections and patches.
 
324
 
 
325
Stas Bekman E<lt>stas *at* stason.orgE<gt>
 
326
 
 
327
=head1 Authors
 
328
 
 
329
=over
 
330
 
 
331
=item * 
 
332
 
 
333
Doug MacEachernE<lt>dougm (at) covalent.netE<gt>
 
334
 
 
335
=item *
 
336
 
 
337
Stas Bekman E<lt>stas (at) stason.orgE<gt>
 
338
 
 
339
=back
 
340
 
 
341
Only the major authors are listed above. For contributors see the
 
342
Changes file.
 
343
 
 
344
=cut
 
345