source: codes/icosagcm/trunk/tools/FCM/doc/standards/perl_standard.html @ 10

Last change on this file since 10 was 10, checked in by ymipsl, 12 years ago

dynamico tree creation

YM
File size: 11.1 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<head>
5  <title>Perl coding standard for FCM</title>
6  <meta name="author" content="FCM development team">
7  <meta name="descriptions" content="Perl coding standard for FCM">
8  <meta name="keywords" content="Perl, coding standard, FCM">
9  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
10  <link rel="StyleSheet" type="text/css" href="style.css">
11  <style type="text/css">
12  <!--
13  li, th, td {
14    padding: 3px;
15  }
16  td {
17    vertical-align: top;
18  }
19  th.r {
20    text-align: right;
21    background-color: transparent;
22    padding-right: 5px;
23  }
24  th.l {
25    text-align: left;
26    background-color: transparent;
27  }
28  -->
29  </style>
30</head>
31
32<body>
33  <p align="right"><img src="logo.png" alt="Met Office logo" width="85"
34  height="85"></p>
35
36  <h1>Perl coding standard for FCM</h1>
37
38  <p align="center">Met Office<br>
39  FitzRoy Road, Exeter<br>
40  Devon, EX1 3PB<br>
41  United Kingdom</p>
42
43  <p align="center">&copy; Crown copyright 2005-6. All rights reserved.</p>
44
45  <p align="center">Questions regarding this document or permissions to quote
46  from it should be directed to the <a href=
47  "mailto:iprmanager@metoffice.gov.uk">IPR Manager</a>.</p>
48
49  <h2>Contents</h2>
50
51  <ul>
52    <li>Main contents:
53
54      <ol>
55        <li><a href="#1">Introduction</a></li>
56
57        <li><a href="#2">Online Perl style guides</a></li>
58
59        <li><a href="#3">Coding standard</a></li>
60      </ol>
61    </li>
62  </ul><a name="1"></a>
63
64  <h2>1. Introduction</h2>
65
66  <p>Perl (Practical Extraction and Report Language) is gaining a lot of
67  popularity at the Met Office for developing applications that are
68  traditionally programmed using shell script. For example, it is currently our
69  choice of language for developing the in-house components of the FCM
70  system.</p>
71 
72  <p>Perl is a very powerful general purpose scripting tool that is free and
73  portable across a huge variety of platforms including many non-Unix systems.
74  Replacing a shell script with an equivalent Perl program often results in a
75  massive reduction in runtime - using cleaner syntax and algorithm.</p>
76
77  <p>Perl is a language with a rich set of "grammar". To most people, the first
78  impression of a piece of code written in Perl is that it is very ugly. Its
79  lines are full of punctuation junks that nobody can hope to understand. This
80  is often caused by poorly written programs coupled with little and often
81  inadequte documentations. To improve readability and to reduce the overheads
82  of maintenance, it is important for Perl programmers to write their code in a
83  nice and consistent way.</p>
84
85  <p>The aim of this document is to propose ideas on how the Perl programming
86  language should be used with FCM.</p>
87
88  <a name="2"></a><h2>2. Online Perl style guides</h2>
89
90  <p>There are many Perl style guides available online. Some are listed
91  below:</p>
92
93  <ul>
94    <li>the manpages <code>perlstyle</code> and <code>perlmodstyle</code></li>
95
96    <li><a href=
97    "http://www.kulnet.kuleuven.ac.be/perlcourse/perlingo.html">Perlingo</a></li>
98
99    <li><a href="http://ali.as/devel/code.html">Perl Style Guide for Large Scale
100    Object Oriented Development</a></li>
101
102    <li><a href="http://perltidy.sourceforge.net/">Perltidy</a></li>
103
104    <li><a href=
105    "http://perl.apache.org/docs/2.0/devel/core/coding_style.pdf">mod_perl
106    Coding Style Guide</a> (PDF)</li>
107  </ul>
108
109  <p>It is worth noting that the ideas in some of the Perl style guides may
110  conflict with each other - as they are targeted to different people. However,
111  there is a common theme to most of the best practices. The following is a
112  summary:</p>
113
114  <ul>
115    <li>A source file, whether it is a top-level script or a module, should
116    contain a header block with information of the source file,
117    some general description of the code as well as standard pragmas or
118    options for running the Perl interpreter.</li>
119
120    <li>Each function should be preceded by a comment block or a block of
121    POD to specify a synopsis for the defined function.</li>
122
123    <li>Avoid using names of built-in functions to name your new functions.</li>
124
125    <li>If the parameter list of a function is becoming too long, e.g. more
126    than 3 arguments, you may want to implement the argument list with a hash,
127    so that all the arguments are named.</li>
128
129    <li>Indent to an appropriate number of spaces/tabs for code blocks.</li>
130
131    <li>Open curly brackets should be on the same line as the keyword.</li>
132
133    <li>Close curly brackets should line up with the keywords that started
134    the block.</li>
135
136    <li>Insert a blank line between chunks of code that do different
137    things.</li>
138
139    <li>Use space between tokens and operators to improve readability.
140    Use space after commas. No space before commas and semi-colons.</li>
141
142    <li>Line up corresponding items vertically.</li>
143
144    <li>Use parentheses only if necessary.</li>
145
146    <li>Restrict line length to e.g. 80 characters.</li>
147
148    <li>Be consistent with style.</li>
149
150    <li>Use the "strict" and "warnings" pragmas.</li>
151
152    <li>options and arguments should be processed as "soon" as possible,
153    preferably at the beginning of a source file or a function.</li>
154
155    <li>Use the "__END__" directive at the end of a Perl script.</li>
156
157    <li>-more later-</li>
158  </ul>
159
160  <a name="3"></a><h2>3. Coding standard</h2>
161
162  <p>The main question is: what should we include in our coding standard?
163  Although we would like to recommend using the best practices described in
164  the last section, we would not want to impose any restriction, as Perl is a
165  language designed to do things in many different ways. The only thing we
166  would like to impose is a header block in each source file, and a header
167  comment block for each function in a source file.</p>
168
169  <p>For a Perl executable, the header block of the source file should contain
170  the following:</p>
171 
172  <ul>
173    <li>the first line should be <tt>"#!/usr/bin/perl"</tt></li>
174
175    <li>the name of the executable</li>
176   
177    <li>a synopsis and/or a description or what the executable does</li>
178
179    <li>an explanation of the options and arguments (either in separate
180    sections or described within the "description" section)</li>
181
182    <li>copyright and owner information</li>
183
184    <li>no history or revision information, (as we would prefer using the
185    Subversion log message to record such information)</li>
186
187    <li>use "strict" and use "warnings" statements</li>
188
189    <li>use the "__END__" directive at the end of a Perl script.</li>
190  </ul>
191
192  <table summary="executable header block example" border="1" width="100%">
193    <tr>
194      <th>Executable header block example</th>
195    </tr>
196
197    <tr>
198      <td>
199        <pre>
200#!/usr/bin/perl
201# ------------------------------------------------------------------------------
202# NAME
203#   example.pl
204#
205# SYNOPSIS
206#   example.pl [options] args
207#
208# DESCRIPTION
209#   This is a header example, and so on and so forth.
210#
211# OPTIONS
212#   -b [--bar] - this option does what "bar" does.
213#   -f [--foo] - this option does what "foo" does.
214#
215# ARGUMENTS
216#   args       - description of each argument.
217#
218# SEE ALSO
219#   list of relevant commands, modules and documents
220#
221# COPYRIGHT
222#   (C) Crown copyright Met Office. All rights reserved.
223#   For further details please refer to the file COPYRIGHT.txt
224#   which you should have received as part of this distribution.
225# ------------------------------------------------------------------------------
226
227# Standard pragmas
228use strict;
229use warnings;
230
231# Standard modules
232use Getopt::Long;
233
234# ------------------------------------------------------------------------------
235
236# Process options
237my ($foo, $bar);
238GetOptions (
239  'foo|f' =&gt; \$foo,
240  'bar|b' =&gt; \$bar,
241);
242
243# Process arguments
244my $arg = shift @ARGV;
245
246# Do something...
247print 'This is an example: ', $arg, "\n";
248print 'FOO', "\n" if $foo;
249print 'BAR', "\n" if $bar;
250
251__END__
252</pre>
253      </td>
254    </tr>
255  </table>
256
257  <p>For a Perl module, the header block of the source file should contain
258  the following:</p>
259 
260  <ul>
261    <li>the first line should be <tt>"#!/usr/bin/perl"</tt></li>
262
263    <li>the name of the module</li>
264   
265    <li>a synopsis and/or a description or what the module does</li>
266
267    <li>copyright and owner information</li>
268
269    <li>no history or revision information</li>
270
271    <li>use "strict" and use "warnings" statements</li>
272
273    <li>a list of exports (do not export if you are writing an OO module)</li>
274
275    <li>use the "__END__" directive at the end of a Perl script, and remember
276    to put 1 before the end of the module, so that it will return true.</li>
277  </ul>
278
279  <table summary="module header block example" border="1" width="100%">
280    <tr>
281      <th>Module header block example</th>
282    </tr>
283
284    <tr>
285      <td>
286        <pre>
287#!/usr/bin/perl
288# ------------------------------------------------------------------------------
289# NAME
290#   Metoffice::Example
291#
292# DESCRIPTION
293#   This is a header example, and so on and so forth.
294#
295# SEE ALSO
296#   list of relevant commands, modules and documents
297#
298# COPYRIGHT
299#   (C) Crown copyright Met Office. All rights reserved.
300#   For further details please refer to the file COPYRIGHT.txt
301#   which you should have received as part of this distribution.
302# ------------------------------------------------------------------------------
303
304package Metoffice::Example;
305
306# Standard pragmas
307use strict;
308use warnings;
309
310# Exports
311our (@ISA, @EXPORT, @EXPORT_OK);
312require Exporter;
313@ISA    = qw(Exporter);
314@EXPORT = qw(
315  foo
316  bar
317);
318
319# ------------------------------------------------------------------------------
320# ... some more Perl ...
321# ------------------------------------------------------------------------------
322
3231;
324
325__END__
326</pre>
327      </td>
328    </tr>
329  </table>
330
331  <p>The header of a function (or "method" for OO code) should have the
332  following:</p>
333
334  <ul>
335    <li>a synopsis of the function's calling interfaces.</li>
336
337    <li>a description of what the function does and what it returns, and if
338    appropriate, what each argument represents</li>
339  </ul>
340
341  <table summary="function header block example" border="1" width="100%">
342    <tr>
343      <th>Function header block example</th>
344    </tr>
345
346    <tr>
347      <td>
348        <pre>
349# ... Something before the function ...
350#
351# ------------------------------------------------------------------------------
352# SYNOPSIS
353#   $result = &amp;print_hello;
354#   $result = &amp;print_hello ($arg);
355#
356# DESCRIPTION
357#   Print the word "hello" to standard output. If no argument is specified,
358#   the word "world" will be printed after the word "hello". Otherwise, the
359#   word specified by the argument $arg will follow "hello". The function
360#   returns true on success.
361#
362# ARGUMENTS
363#   $arg - optional, describe $arg if it has not been done in the above section
364# ------------------------------------------------------------------------------
365
366sub print_hello {
367  my ($arg) = @_;
368  $arg = defined ($arg) ? $arg : 'world';
369  my $result = print 'hello ', $arg, "\n";
370  return $result;
371}
372
373# ------------------------------------------------------------------------------
374#
375# ... Something after the function ...
376</pre>
377      </td>
378    </tr>
379  </table>
380
381  <script type="text/javascript" src="maintain.js">
382  </script>
383</body>
384</html>
Note: See TracBrowser for help on using the repository browser.