source: LMDZ5/trunk/tools/fcm/doc/standards/perl_standard.html @ 4249

Last change on this file since 4249 was 1578, checked in by jghattas, 13 years ago
  • Add fcm in LMDZ5/tools directory

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