source: codes/icosagcm/trunk/tools/FCM/doc/standards/fortran_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: 39.4 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<head>
5  <title>Fortran coding standard for FCM</title>
6  <meta name="author" content="FCM team">
7  <meta name="descriptions" content="Fortran coding standard for FCM">
8  <meta name="keywords" content="Fortran, 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  mono {
20    font-family: monospace;
21  }
22  -->
23  </style>
24</head>
25
26<body>
27  <p align="right"><img src="logo.png" alt="Met Office logo" width="85"
28  height="85"></p>
29
30  <h1>Fortran coding standard for FCM</h1>
31
32  <p align="center">Met Office<br>
33  FitzRoy Road, Exeter<br>
34  Devon, EX1 3PB<br>
35  United Kingdom</p>
36
37  <p align="center">&copy; Crown copyright 2006. All rights reserved.</p>
38
39  <p align="center">Questions regarding this document or permissions to quote
40  from it should be directed to the <a href=
41  "mailto:iprmanager@metoffice.gov.uk">IPR Manager</a>.</p>
42
43  <h2>Contents</h2>
44
45  <p>Main contents:</p>
46
47  <ol>
48    <li><a href="#intro">Introduction</a></li>
49
50    <li>
51      <a href="#fcm">Programming Fortran for the FCM build system</a>
52
53      <ul>
54        <li><a href="#fcm-general">General</a></li>
55
56        <li><a href="#fcm-cpp">Use of C pre-processor</a></li>
57      </ul>
58    </li>
59
60    <li>
61      <a href="#fortran">Programming Fortran in general</a>
62
63      <ul>
64        <li><a href="#fortran-layout">Layout and formatting</a></li>
65
66        <li><a href="#fortran-style">Style</a></li>
67
68        <li><a href="#fortran-feature">Fortran features</a></li>
69      </ul>
70    </li>
71
72    <li><a href="#template">Program templates</a></li>
73  </ol>
74
75  <h2><a name="intro"></a>1. Introduction</h2>
76
77  <p>Fortran is the standard programming language at the Met Office for
78  developing scientific and research applications, in particular, for programs
79  running on the supercomputers. This document describes some guidelines that
80  should be followed by developers when writing Fortran code, especially for
81  code in systems hosted by FCM.</p>
82
83  <h2><a name="fcm"></a>2. Programming Fortran for the FCM build system</h2>
84
85  <h3><a name="fcm-general"></a>2.1 General</h3>
86
87  <p>To get the most out of the FCM build system, you should follow these
88  guidelines when you develop your code:</p>
89
90  <ol>
91    <li>Each source file should contain one and no more than one top level
92    program unit, (such as a PROGRAM, a standalone SUBROUTINE/FUNCTION or a
93    MODULE). All top level standalone program units in a source tree should be
94    uniquely named. ("Top level" means a standalone program unit that is
95    compilable independently, i.e. this rule does not restrict the naming and
96    placements of sub-programs in a CONTAINS section.) FCM may fail to set up
97    the dependency tree of your source correctly if you do not follow this rule.
98
99      <p>A clash of program unit names happens most often when you have multiple
100      versions of the same program unit in the same source tree. You should
101      design your code to avoid this situation. If it is not possible to do so,
102      you may have to use a pre-processor to ensure that there is only one copy
103      of each program unit in the source tree. Another situation where clashes
104      of program unit names may occur is when you are developing code that is
105      shared between several projects. In this case, you may want to agree with
106      the other projects a naming convention to define a unique namespace for
107      program units in each project. (E.g. some projects at the Met Office have
108      adopted a naming convention such that all shared program units in a
109      project are named with a unique prefix.)</p>
110    </li>
111
112    <li>All code should be written using the free source form. (At Fortran 95,
113    the free source form can have a maximum of 132 characters per line, and up
114    to 39 continuations in a Fortran statement.) The fixed source form is
115    obsolete, and is not supported by the interface file generators used by
116    FCM.</li>
117
118    <li>An interface should be provided when calling a SUBROUTINE or a FUNCTION.
119    Not only is this considered good practice, it also allows FCM to determine
120    the dependency relationship of your source files. An interface can be
121    provided in these ways:
122
123      <table summary="interface - internal procedures" width="100%" border="1">
124        <tr>
125          <th colspan="2">Internal sub-program</th>
126        </tr>
127
128        <tr>
129          <td colspan="2">Place sub-programs in the CONTAINS section of a
130          standalone program unit. There are two advantages for this approach.
131          Firstly, the sub-programs will get an automatic interface when the
132          container program unit is compiled. Secondly, it should be easier for
133          the compiler to provide optimisation when the sub-programs are
134          internal to the caller.  The disadvantage of this approach is that the
135          sub-programs are local to the caller, and so they cannot be called by
136          other program units.  Therefore, this approach is only suitable for
137          small sub-programs local to a particular program unit.
138       
139            <p>Note: One way to share a sub-program unit between several top
140            level program units is to make use of the Fortran INCLUDE statement.
141            You can write the sub-program unit in a separate file and place it
142            in the CONTAINS section of different program units using INCLUDE
143            statements.  The disadvantage of this approach is that when the
144            program is compiled, a copy of the sub-program unit will be embedded
145            within each of the top level program units. This may lead to an
146            increase in size of the executable, and so this approach is still
147            only suitable for small sub-programs local to a small number of
148            program units.</p>
149
150            <p>Example:</p>
151          </td>
152        </tr>
153
154        <tr>
155          <td width="50%">In the file "sub_prog.inc":
156
157            <pre>
158SUBROUTINE sub_prog (some, arg)
159! Some declarations ...
160! Some executable statements ...
161END SUBROUTINE sub_prog
162</pre>
163          </td>
164
165          <td>In the file "bar.f90":
166
167            <pre>
168SUBROUTINE bar (more, arg)
169! Some declarations ...
170! Some executable statements ...
171CALL sub_prog (some, arg)
172! More executable statements ...
173CONTAINS
174  INCLUDE 'sub_prog.inc'
175END SUBROUTINE bar
176</pre>
177          </td>
178        </tr>
179      </table>
180
181      <table summary="interface - module procedures" width="100%" border="1">
182        <tr>
183          <th colspan="2">Module procedures</th>
184        </tr>
185
186        <tr>
187          <td colspan="2">Place sub-programs in the CONTAINS section of a
188          MODULE. Again, the sub-programs will have automatic interfaces when
189          the MODULE is compiled.  If you give the sub-programs the PUBLIC
190          attribute (which is the default), you will be able to call them from
191          anywhere using the current MODULE. You will also gain all the
192          advantages offered by a MODULE. (E.g. a MODULE will allow you to
193          design your code in a more object-oriented manner.) However, MODULE
194          dependency can have an impact on the efficiency of incremental
195          compilations. For example, if you modify items that are local to the
196          MODULE, it is very difficult for the build system to detect that your
197          change does not affect program units using the MODULE, so the build
198          system will end up compiling the MODULE and all the program units that
199          use it.
200
201            <p>Example:</p>
202          </td>
203        </tr>
204
205        <tr>
206          <td width="50%">In the file "my_mod.f90":
207
208            <pre>
209MODULE my_mod
210! Some module declarations
211CONTAINS
212  SUBROUTINE sub_prog (some, arg)
213  ! Some declarations ...
214  ! Some executable statements ...
215  END SUBROUTINE sub_prog
216END MODULE my_mod
217</pre>
218          </td>
219
220          <td>In the file "foo.f90":
221
222            <pre>
223SUBROUTINE foo (some, arg)
224USE my_mod, ONLY: sub_prog
225! Some declarations ...
226! Some executable statements ...
227CALL sub_prog (some, arg)
228! More executable statements ...
229END SUBROUTINE foo
230</pre>
231          </td>
232        </tr>
233      </table>
234
235      <table summary="interface - interface files" width="100%" border="1">
236        <tr>
237          <th colspan="2">Interface files</th>
238        </tr>
239
240        <tr>
241          <td colspan="2">For each source file containing a standalone
242          SUBROUTINE or FUNCTION, FCM generates a file containing the interface
243          of the SUBROUTINE or FUNCTION. By default, the generated file is named
244          after the original source file, but with the file extension replaced
245          by "*.interface". In the specification section of the caller routine,
246          you will then be able to declare the interface using a Fortran INCLUDE
247          statement to include the interface file. This type of INCLUDE
248          statement is detected automatically by FCM, which will use it to set
249          up the dependency tree.
250       
251            <p>The advantage of using an interface file is that the caller is
252            now dependent on the interface file, rather than the SUBROUTINE or
253            FUNCTION itself. If you change the SUBROUTINE or FUNCTION without
254            modifying its interface, the build system will not re-compile the
255            caller in incremental build, (but it will be intelligent enough to
256            re-link the executable with the updated object).</p>
257
258            <p>Note: By default, an interface file is named after the original
259            source file. Bearing this in mind, it is worth noting that file
260            names in a Unix/Linux system are case-sensitive, and so the
261            interface file name declared by your INCLUDE statement is also case
262            sensitive. If you use an incorrect case in the INCLUDE statement,
263            the dependency tree will be set up incorrectly and the compilation
264            will fail. Another problem is that if you do not name your file
265            after the program unit, the dependency tree will be wrong. To avoid
266            this problem, it is recommended that all source files are named in
267            lower case after the program units they contain. (Alternatively, you
268            can use the TOOL::INTERFACE option in the FCM build configuration
269            file to allow you to alter the default behaviour so that the
270            interface file is named after the "program" unit in lowercase. We
271            may alter FCM in the future so that this will become the default. In
272            the mean time, it is highly recommended that you use this option and
273            design your new code accordingly.)</p>
274
275            <p>Example:</p>
276          </td>
277        </tr>
278
279        <tr>
280          <td width="50%">In the file "sub_prog.f90":
281
282            <pre>
283SUBROUTINE sub_prog (some, arg)
284! Some declarations ...
285! Some executable statements ...
286END SUBROUTINE sub_prog
287</pre>
288          </td>
289
290          <td>In the file "egg.f90":
291
292            <pre>
293SUBROUTINE egg (some, arg)
294! Some declarations ...
295INCLUDE 'sub_prog.interface'
296! More declarations ...
297! Some executable statements ...
298CALL sub_prog (some, arg)
299! More executable statements ...
300END SUBROUTINE egg
301</pre>
302          </td>
303        </tr>
304      </table>
305
306      <table summary="interface - interfaces in a module" width="100%" border="1">
307        <tr>
308          <th colspan="2">Interfaces in a module</th>
309        </tr>
310
311        <tr>
312          <td colspan="2">There is also a half-way house approach between the
313          second and the third options. You can have a dedicated MODULE where a
314          large number of INCLUDE interface file statements are placed. Other
315          program units get their interfaces by importing from this MODULE. A
316          major disadvantage of this approach is that the sub-programs with
317          their interfaces declared within this MODULE will not be able to call
318          any other sub-programs declared within the same MODULE, as it will run
319          into a cyclic dependency problem. Another disadvantage is that if an
320          interface changes, the MODULE and all program units depending on the
321          MODULE will have to be re-compiled, even though the change may be
322          unrelated to some or all of these program units. For these reasons,
323          this approach is only good if you have a bundle of sub-programs that
324          have relatively stable interfaces and are very much independent of one
325          another.
326
327            <p>Note: a similar approach can be useful when you have a library of
328            legacy or external code. In this situation, you will simply declare
329            the interfaces for all the library sub-programs in the MODULE. Any
330            programs that call sub-programs within the library can then import
331            their interfaces by using the MODULE.</p>
332
333            <p>Example:</p>
334          </td>
335        </tr>
336
337        <tr>
338          <td width="50%">In the file "my_i_mod.f90":
339
340            <pre>
341MODULE my_i_mod
342! Some declarations
343INCLUDE 'sub_prog.interface'
344! More declarations
345END MODULE my_i_mod
346</pre>
347          </td>
348
349          <td>In the file "ham.f90":
350
351            <pre>
352SUBROUTINE ham (some, arguments)
353USE my_i_mod, ONLY: sub_prog
354! Some declarations ...
355! Some executable statements ...
356CALL sub_prog (some, arguments)
357! More executable statements ...
358END SUBROUTINE ham
359</pre>
360          </td>
361        </tr>
362      </table>
363
364      <p>FCM also supports the use of a <tt>"! DEPENDS ON"</tt> directive for
365      users to specify a dependency from within a source file. This feature is
366      documented in the <a href=
367      "../user_guide/build.html#advanced_dependency">Further dependency
368      features</a> sub-section of the <a href="../user_guide/">FCM user
369      guide</a>. However, it is worth noting that this method is only included
370      in FCM to support legacy code. It is not a feature recommended for new
371      code, and its use should be gradually phased out from existing code.</p>
372    </li>
373
374    <li>Arguments and local variables should be declared in different
375    statements. It makes your declaration clearer, and it is friendlier to the
376    interface file generator.
377
378      <table summary="declaration example" border="1" width="100%">
379        <tr>
380          <th width="50%">Common practice</th>
381
382          <th>Better approach</th>
383        </tr>
384
385        <tr>
386          <td>
387            <pre>
388SUBROUTINE foo (a, b, c)
389
390INTEGER :: a, b, c, i, j, k
391
392! ...
393
394END SUBROUTINE foo
395</pre>
396          </td>
397
398          <td>
399            <pre>
400SUBROUTINE foo (a, b, c)
401
402INTEGER :: a, b, c
403
404INTEGER :: i, j, k
405
406! ...
407
408END SUBROUTINE foo
409</pre>
410          </td>
411        </tr>
412      </table>
413    </li>
414
415    <li>Use the ONLY clause in a USE &lt;module&gt; statement to declare all
416    imported symbols (i.e. parameters, variables, functions, subroutines, etc).
417    This makes it easier to locate the source of each symbol, and avoids
418    unintentional access to other PUBLIC symbols within the MODULE. It is also
419    friendlier to the compiler and the interface file generator, as they will
420    not have to import modules and symbols that are unnecessary.</li>
421
422    <li>In its default settings, FCM recognises the following file extensions
423    as Fortran free format source files:
424
425      <ul>
426        <li>*.f90, *.f95: regular Fortran free format source files</li>
427
428        <li>*.F90, *.F95: Fortran free format source files that require
429        pre-processing</li>
430
431        <li>*.inc: INCLUDE files that can be added to a regular Fortran free
432        format source file with a Fortran INCLUDE statement</li>
433      </ul>
434    </li>
435  </ol>
436
437  <h3><a name="fcm-cpp"></a>2.2 Use of C pre-processor with Fortran</h3>
438
439  <p>We do not recommend the use of C pre-processor with Fortran. However, it is
440  acknowledged that there are some situations when it is necessary to
441  pre-process Fortran code. FCM supports pre-processing in two ways.
442  Pre-processing can be left to the compiler or it can be done in a separate
443  early stage of the build process. A separate pre-process stage can be useful
444  if pre-processing changes any of the following in a program unit:</p>
445
446  <ul>
447    <li>its name</li>
448
449    <li>its calling interface</li>
450
451    <li>its dependencies</li>
452  </ul>
453
454  <p>However, using a separate pre-process stage is not the best way of working,
455  as it adds an overhead to the build process. If your code requires
456  pre-processing, you should try to design it to avoid changes in the above.</p>
457
458  <p>In practice, the only reasonable use of C pre-processor with Fortran is for
459  code selection. For example, pre-processing is useful for isolating machine
460  specific libraries or instructions, where it may be appropriate to use inline
461  alternatives for small sections of code. Another example is when multiple
462  versions of the same procedure exist in the source tree and you need to use
463  the pre-processor to select the correct version for your build.</p>
464
465  <p>Avoid using the C pre-processor for code inclusion, as you should be able
466  to do the same via the Fortran INCLUDE statement. You should also avoid
467  embedding pre-processor macros within the continuations of a Fortran
468  statement, as it can make your code very confusing.</p>
469
470  <h2><a name="fortran"></a>3. Programming Fortran in general</h2>
471
472  <p>The guidelines in this section are recommended practices for programming
473  Fortran in general. These are guidelines you should try to adhere to when you
474  are developing new code. If you are modifying existing code, you should adhere
475  to its existing standard and style where possible. If you want to change its
476  standard and style, you should seek prior agreements with the owner and the
477  usual developers of the code. Where possible, you should try to maintain the
478  same layout and style within a source file, and preferably, within all the
479  source code in a particular project.</p>
480
481  <p>When reading these guidelines, it is assumed that you already have a good
482  understanding of modern Fortran terminology. It is understood that these
483  guidelines may not cover every aspect of your work. In such cases, you will
484  be a winner if you use a bit of common sense, and always bearing in mind that
485  some other people may have to maintain the code in the future.</p>
486
487  <p>Always test your code before releasing it. Do not ignore compiler warnings,
488  as they may point you to potential problems.</p>
489
490  <h3><a name="fortran-layout"></a>3.1 Layout and formatting</h3>
491
492  <p>The following is a list of recommended practices for layout and formatting
493  when you write code in Fortran.</p>
494
495  <ul>
496    <li>Indent blocks by 2 characters. Where possible, comments should be
497    indented with the code within a block.</li>
498
499    <li>Use space and blank lines where appropriate to format your code to
500    improve readability. (Use genuine spaces but avoid using tabs, as the "tab"
501    character is not in the Fortran character set.) In the following example,
502    the code on the right hand side is preferred:
503
504      <table summary="space example" border="1" width="100%">
505        <tr>
506          <th width="50%">Common practice</th>
507
508          <th>Better approach</th>
509        </tr>
510
511        <tr>
512          <td>
513            <pre>
514DO i=1,n
515  a(i)%c=10*i/n
516  b(i)%d=20+i
517ENDDO
518IF(this==that)THEN
519  distance=0
520  time=0
521ENDIF
522</pre>
523          </td>
524
525          <td>
526            <pre>
527DO i = 1, n
528  a(i) % c = 10 * i / n
529  b(i) % d = 20 + i
530END DO
531
532IF (this == that) THEN
533  distance = 0
534  time     = 0
535END IF
536</pre>
537          </td>
538        </tr>
539      </table>
540    </li>
541
542    <li>Try to confine your line width to 80 characters, so that your code can
543    be printed easily on A4 paper.</li>
544
545    <li>Line up your statements, where appropriate, to improve readability. For
546    example:
547
548      <table summary="line up example" border="1" width="100%">
549        <tr>
550          <th width="50%">Common practice</th>
551
552          <th>Better approach</th>
553        </tr>
554
555        <tr>
556          <td>
557            <pre>
558REAL, INTENT (OUT) :: my_out (:)
559REAL, INTENT (INOUT) :: my_inout (:)
560REAL, INTENT (IN) :: my_in  (:)
561
562! ...
563
564CHARACTER (LEN = 256) :: my_char
565
566my_char = 'This is a very very' // &amp;
567  ' very very very long' // &amp;
568  ' character assignment'.
569</pre>
570          </td>
571
572          <td>
573            <pre>
574REAL, INTENT (  OUT) :: my_out   (:)
575REAL, INTENT (INOUT) :: my_inout (:)
576REAL, INTENT (IN   ) :: my_in    (:)
577
578! ...
579
580CHARACTER (LEN = 256) :: my_char
581
582my_char = 'This is a very very'  // &amp;
583          ' very very very long' // &amp;
584          ' character assignment'.
585</pre>
586          </td>
587        </tr>
588      </table>
589    </li>
590
591    <li>Short and simple Fortran statements are easier to read and understand
592    than long and complex ones. Where possible, avoid using continuation lines
593    in a statement.</li>
594
595    <li>Avoid putting multiple statements on the same line. It is not good for
596    readability.</li>
597  </ul>
598
599  <h3><a name="fortran-style"></a>3.2 Style</h3>
600
601  <p>The following is a list of recommended styles when you write code in
602  Fortran.</p>
603
604  <ul>
605    <li>New code should be written using Fortran 95 syntax. Avoid unportable
606    vendor/compiler extensions. Avoid Fortran 2003 features for the moment, as
607    they will not become widely available in the near future. (Having said that,
608    there is no harm in designing your code with the future in mind. For
609    example, if there is a feature that is not in Fortran 95 and you know that
610    it is in Fortran 2003, you may want to write your Fortran 95 code to make it
611    easier for the future upgrade.)</li>
612
613    <li>Write your program in UK English, unless you have a very good reason for
614    not doing so. Write your comments in simple UK English and name your program
615    units and variables based on sensible UK English words, bearing in mind that
616    your code may be read by people who are not proficient English
617    speakers.</li>
618
619    <li>When naming your variables and program units, always bear in mind that
620    Fortran is a case-insensitive language. (E.g. EditOrExit is the same as
621    EditorExit.)</li>
622
623    <li>Use only characters in the Fortran character set. In particular, accent
624    characters and tabs are not allowed in code, although they are usually OK
625    in comments. If your editor inserts tabs automatically, you should
626    configure it to switch off the functionality when you are editing Fortran
627    source files.</li>
628
629    <li>Although Fortran has no reserved keywords, you should avoid naming your
630    program units and variables with names that match an intrinsic FUNCTION or
631    SUBROUTINE. Similarly, you should avoid naming your program units and
632    variables with names that match a "keyword" in a Fortran statement.</li>
633
634    <li>Be generous with comments. State the reason for doing something,
635    instead of repeating the Fortran logic in words.</li>
636
637    <li>To improve readability, write your program in mainly lower case
638    characters. Writing a program in mainly lower case also means that you will
639    not have to use the Shift/Caps Lock keys often. There is a lot of debate on
640    using upper/lower cases in a case insensitive language such as Fortran.
641    There is no right or wrong, but people have adopted the different approaches
642    over time, each has its own merit. If you are starting a new project, you
643    should choose a suitable option and stick to it. Otherwise, you should stick
644    with the style in the existing code. Some options are listed here:
645
646      <ul>
647        <li>The ALL CAPS Fortran keywords approach, like most of the examples in
648        this document, where all Fortran keywords and intrinsic procedures are
649        written in ALL CAPS. This approach has the advantage that Fortran
650        keywords stand out, but it does increase how often the Shift/Caps Lock
651        key is used. Programmers who are used to some other programming
652        languages may also find it difficult to read a program with a lot of
653        upper case characters.</li>
654
655        <li>The Title Case Fortran keywords approach, where all Fortran keywords
656        are written with an initial capital case letter.</li>
657
658        <li>The sentence case approach, where only the initial character in a
659        Fortran statements is written in capital case letter, like a normal
660        sentence.</li>
661
662        <li>The all lower case approach, where all Fortran keywords are written
663        in lower case letters.</li>
664
665        <li>Some people have also proposed a variable naming convention where
666        local variables start with an initial lower case letter, private
667        module level variables with an initial capital case letter and public
668        module variables written in all caps. However, this approach has been
669        seen by many as too restrictive, and so its use has not been widely
670        spread.</li>
671      </ul>
672    </li>
673
674    <li>Use the new and clearer syntax for LOGICAL comparisons, i.e.:
675
676      <ul>
677        <li>== instead of .EQ.</li>
678
679        <li>/= instead of .NE.</li>
680
681        <li>&gt; instead of .GT.</li>
682
683        <li>&lt; instead of .LT.</li>
684
685        <li>&gt;= instead of .GE.</li>
686
687        <li>&lt;= instead of .LE.</li>
688      </ul>
689    </li>
690
691    <li>Where appropriate, simplify your LOGICAL assignments, for example:
692
693      <table summary="logic assignment example" border="1" width="100%">
694        <tr>
695          <th width="50%">Common practice</th>
696
697          <th>Better approach</th>
698        </tr>
699
700        <tr>
701          <td>
702            <pre>
703IF (my_var == some_value) THEN
704  something      = .TRUE.
705  something_else = .FALSE.
706
707ELSE
708  something      = .FALSE.
709  something_else = .TRUE.
710END IF
711
712IF (something .EQV. .TRUE.) THEN
713  CALL do_something ()
714  ! ...
715END IF
716</pre>
717          </td>
718
719          <td>
720            <pre>
721something      = (my_var == some_value)
722something_else = (my_var /= some_value)
723
724IF (something) THEN
725  CALL do_something ()
726  ! ...
727END IF
728</pre>
729          </td>
730        </tr>
731      </table>
732    </li>
733
734    <li>Positive logic is usually easier to understand. When you have an
735    IF-ELSE-END IF construct, you should use positive logic in the IF test,
736    provided that the positive and the negative blocks are about the same size.
737    (However, it may be more appropriate to use negative logic if the negative
738    block is significantly bigger than the positive block.) For example:
739
740      <table summary="positive logic example" border="1" width="100%">
741        <tr>
742          <th width="50%">Common practice</th>
743
744          <th>Better approach</th>
745        </tr>
746
747        <tr>
748          <td>
749            <pre>
750IF (my_var != some_value) THEN
751  CALL do_this ()
752
753ELSE
754  CALL do_that ()
755END IF
756</pre>
757          </td>
758
759          <td>
760            <pre>
761IF (my_var == some_value) THEN
762  CALL do_that ()
763
764ELSE
765  CALL do_this ()
766END IF
767</pre>
768          </td>
769        </tr>
770      </table>
771    </li>
772
773    <li>To improve readability, you should always use the optional space to
774    separate the following Fortran keywords:
775
776      <table summary="space in Fortran keywords" width="100%">
777        <tr class="mono">
778          <td width="25%">else if</td>
779
780          <td width="25%">end do</td>
781
782          <td width="25%">end forall</td>
783
784          <td width="25%">end function</td>
785        </tr>
786
787        <tr class="mono">
788          <td width="25%">end if</td>
789
790          <td width="25%">end interface</td>
791
792          <td width="25%">end module</td>
793
794          <td width="25%">end program</td>
795        </tr>
796
797        <tr class="mono">
798          <td width="25%">end select</td>
799
800          <td width="25%">end subroutine</td>
801
802          <td width="25%">end type</td>
803
804          <td width="25%">end where</td>
805        </tr>
806
807        <tr class="mono">
808          <td width="25%">select case</td>
809
810          <td width="25%">-</td>
811
812          <td width="25%">-</td>
813
814          <td width="25%">-</td>
815        </tr>
816      </table>
817    </li>
818
819    <li>If you have a large or complex code block embedding other code blocks,
820    you may consider naming some or all of them to improve readability.</li>
821
822    <li>If you have a large or complex interface block or if you have one or
823    more sub-program units in the CONTAINS section, you can improve readability
824    by using the full version of the END statement (i.e. END SUBROUTINE
825    &lt;name&gt; or END FUNCTION &lt;name&gt; instead of just END) at the end of
826    each sub-program unit. For readability in general, the full version of the
827    END statement is recommended over the simple END.</li>
828
829    <li>Where possible, consider using CYCLE, EXIT or a WHERE-construct to
830    simplify complicated DO-loops.</li>
831
832    <li>When writing a REAL literal with an integer value, put a 0 after the
833    decimal point (i.e. 1.0 as opposed to 1.) to improve readability.</li>
834
835    <li>Where reasonable and sensible to do so, you should try to match the
836    names of dummy and actual arguments to a SUBROUTINE/FUNCTION.</li>
837
838    <li>In an array assignment, it is recommended that you use array notations
839    to improve readability. E.g.:
840
841      <table summary="array notation example" border="1" width="100%">
842        <tr>
843          <th width="50%">Common practice</th>
844
845          <th>Better approach</th>
846        </tr>
847
848        <tr>
849          <td>
850            <pre>
851INTEGER :: array1(10, 20), array2(10, 20)
852INTEGER :: scalar
853
854array1 = 1
855array2 = array1 * scalar
856</pre>
857          </td>
858
859          <td>
860            <pre>
861INTEGER :: array1(10, 20), array2(10, 20)
862INTEGER :: scalar
863
864array1(:, :) = 1
865array2(:, :) = array1(:, :) * scalar
866</pre>
867          </td>
868        </tr>
869      </table>
870    </li>
871
872    <li>Where appropriate, use parentheses to improve readability. E.g.:
873
874      <table summary="parentheses example" border="1" width="100%">
875        <tr>
876          <th width="50%">Common practice</th>
877
878          <th>Better approach</th>
879        </tr>
880
881        <tr>
882          <td>
883            <pre>
884a = b * i + c / n
885</pre>
886          </td>
887
888          <td>
889            <pre>
890a = (b * i) + (c / n)
891</pre>
892          </td>
893        </tr>
894      </table>
895    </li>
896  </ul>
897
898  <h3><a name="fortran-feature"></a>3.3 Fortran features</h3>
899
900  <p>The following is a list of Fortran features that you should use or
901  avoid.</p>
902
903  <ul>
904    <li>Use IMPLICIT NONE in all program units. It means that you have declare
905    all your variables explicitly. This helps to reduce bugs in your program
906    that will otherwise be difficult to track.</li>
907
908    <li>Design your derived data types carefully and use them to group related
909    variables. Appropriate use of derived data types will allow you to design
910    modules and procedures with simpler and cleaner interfaces.</li>
911
912    <li>Where possible, module variables and procedures should be declared
913    PRIVATE. This avoids unnecessary export of symbols, promotes data hiding and
914    may also help the compiler to optimise the code.</li>
915
916    <li>When you are passing an array argument to a SUBROUTINE/FUNCTION, and the
917    SUBROUTINE/FUNCTION does not change the SIZE/DIMENSION of the array, you
918    should pass it as an assumed shape array. Memory management of such an array
919    is automatically handled by the SUBROUTINE/FUNCTION, and you do not have to
920    worry about having to ALLOCATE or DEALLOCATE your array. It also helps the
921    compiler to optimise the code.</li>
922
923    <li>Use an array POINTER when you are passing an array argument to a
924    SUBROUTINE, and the SUBROUTINE has to alter the SIZE/DIMENSION of the array.
925    You should also use an array POINTER when you need a dynamic array in a
926    component of a derived data type. (Note: Fortran 2003 allows passing
927    ALLOCATABLE arrays as arguments as well as using ALLOCATABLE arrays as
928    components of a derived data type. Therefore, the need for using an array
929    POINTER should be reduced once Fortran 2003 becomes more widely
930    accepted.)</li>
931
932    <li>Where possible, an ALLOCATE statement for an ALLOCATABLE array (or a
933    POINTER used as a dynamic array) should be coupled with a DEALLOCATE within
934    the same scope. If an ALLOCATABLE array is a PUBLIC MODULE variable, it is
935    highly desirable if its memory allocation and deallocation are only
936    performed in procedures within the MODULE in which it is declared. You may
937    consider writing specific SUBROUTINEs within the MODULE to handle these
938    memory managements.</li>
939
940    <li>To avoid memory fragmentation, it is desirable to DEALLOCATE in reverse
941    order of ALLOCATE.
942
943      <table summary="ALLOCATE example" border="1" width="100%">
944        <tr>
945          <th width="50%">Common practice</th>
946
947          <th>Better approach</th>
948        </tr>
949
950        <tr>
951          <td>
952            <pre>
953ALLOCATE (a(n))
954ALLOCATE (b(n))
955ALLOCATE (c(n))
956! ... do something ...
957DEALLOCATE (a)
958DEALLOCATE (b)
959DEALLOCATE (c)
960</pre>
961          </td>
962
963          <td>
964            <pre>
965ALLOCATE (a(n))
966ALLOCATE (b(n))
967ALLOCATE (c(n))
968! ... do something ...
969DEALLOCATE (c)
970DEALLOCATE (b)
971DEALLOCATE (a)
972</pre>
973          </td>
974        </tr>
975      </table>
976    </li>
977
978    <li>Always define a POINTER before using it. You can define a POINTER in its
979    declaration by pointing it to the intrinsic function NULL (). Alternatively,
980    you can make sure that your POINTER is defined or nullified early on in the
981    program unit. Similarly, NULLIFY a POINTER when it is no longer in use,
982    either by using the NULLIFY statement or by pointing your POINTER to NULL
983    ().</li>
984
985    <li>Avoid the DIMENSION attribute or statement. Declare the DIMENSION with
986    the declared variables. E.g.:
987
988      <table summary="dimension attribute example" border="1" width="100%">
989        <tr>
990          <th width="50%">Common practice</th>
991
992          <th>Better approach</th>
993        </tr>
994
995        <tr>
996          <td>
997            <pre>
998INTEGER, DIMENSION(10) :: array1
999INTEGER                :: array2
1000DIMENSION              :: array2(20)
1001</pre>
1002          </td>
1003
1004          <td>
1005            <pre>
1006INTEGER :: array1(10), array2(20)
1007</pre>
1008          </td>
1009        </tr>
1010      </table>
1011    </li>
1012
1013    <li>Avoid COMMON blocks and BLOCK DATA program units. Use PUBLIC MODULE
1014    variables.</li>
1015
1016    <li>Avoid the EQUIVALENCE statament. Use a POINTER or a derived data type,
1017    and the TRANSFER intrinsic function to convert between types.</li>
1018
1019    <li>Avoid the PAUSE statement, as your program will hang in a batch
1020    environment. If you need to halt your program for interactive use, consider
1021    using a READ* statement instead.</li>
1022
1023    <li>Avoid the ENTRY statement. Use a MODULE or internal SUBROUTINE.</li>
1024
1025    <li>Avoid the GOTO statement. The only commonly acceptable usage of GOTO is
1026    for error trapping. In such case, the jump should be to a commented 9999
1027    CONTINUE statement near the end of the program unit. Typically, you will
1028    only find error handlers beyond the 9999 CONTINUE statement.</li>
1029
1030    <li>Avoid assigned GOTO, arithmetic IF, etc. Use the appropriate modern
1031    constructs such as IF, WHERE, SELECT CASE, etc..</li>
1032
1033    <li>Avoid numbered statement labels. DO ... <em>label</em> CONTINUE
1034    constructs should be replaced by DO ... END DO constructs. FORMAT statements
1035    should be replaced by format strings. (Tip: a format string can be a
1036    CHARACTER variable.)</li>
1037
1038    <li>A FUNCTION should be PURE, i.e. it should have no side effects (e.g.
1039    altering an argument or module variable, or performing I/O). If you need to
1040    perform a task with side effects, you should use a SUBROUTINE instead.</li>
1041
1042    <li>Avoid using a statement FUNCTION. Use an internal FUNCTION instead.</li>
1043
1044    <li>Avoid RECURSIVE procedures if possible. RECURSIVE procedures are usually
1045    difficult to understand, and are always difficult to optimise in a
1046    supercomputer environment.</li>
1047
1048    <li>Avoid using the specific names of intrinsic procedures. Use the generic
1049    names of intrinsic procedures where possible.</li>
1050  </ul>
1051
1052  <h2><a name="template"></a>4. Program templates</h2>
1053
1054  <p>The following is a basic template for a SUBROUTINE:</p>
1055  <pre>
1056SUBROUTINE &lt;subroutine_name&gt; (&lt;arguments&gt;, ...)
1057
1058! Description:
1059!   &lt;Explain the usage of the subroutine and what it does.&gt;
1060!
1061! (c) Crown copyright Met Office. All rights reserved.
1062! For further details please refer to the file COPYRIGHT.txt
1063! which you should have received as part of this distribution.
1064! ------------------------------------------------------------------------------
1065
1066! Modules
1067&lt;module declarations, each with a list of imported symbols&gt;
1068
1069IMPLICIT NONE
1070
1071! Arguments:
1072&lt;arguments with INTENT (  OUT)&gt;
1073&lt;arguments with INTENT (INOUT)&gt;
1074&lt;arguments with INTENT (IN   )&gt;
1075
1076! Local declarations:
1077&lt;parameters, derived data types, variables, etc&gt;
1078
1079! INTERFACE blocks
1080&lt;INCLUDE interface blocks for external procedures&gt;
1081&lt;interface blocks for procedure and operator overloading&gt;
1082
1083!-------------------------------------------------------------------------------
1084
1085&lt;... subroutine executable statements&gt;
1086
1087!-------------------------------------------------------------------------------
1088
1089CONTAINS
1090
1091  &lt;sub-programs&gt;
1092
1093END SUBROUTINE &lt;subroutine_name&gt;
1094</pre>
1095
1096  <p>Note:</p>
1097
1098  <ul>
1099    <li>The basic templates for other types of program units are similar to
1100    that of a SUBROUTINE, with the following exceptions:
1101
1102      <ul>
1103        <li>A PROGRAM does not have arguments, so the "arguments" list in the
1104        header and the "Arguments" section in the declaration section should be
1105        removed. All declarations are local to a PROGRAM, so the "Local
1106        Declarations" section should be replaced by a simple "Declarations"
1107        section.</li>
1108
1109        <li>A FUNCTION should have no INTENT (OUT) and INTENT (INOUT) arguments.
1110        You will also need to declare the type returned by the FUNCTION. This
1111        can be in the FUNCTION header, declared separately or declared using a
1112        RESULT clause. For the latters, make your declaration at the beginning
1113        of the "Local declarations" section.</li>
1114
1115        <li>A MODULE does not have arguments, so the "arguments" list in the
1116        header and the "Arguments" section in the declaration section should be
1117        removed. Where appropriate, the "Local Declarations" section should be
1118        replaced by a "PUBLIC declarations" section and a "PRIVATE declarations"
1119        section.</li>
1120      </ul>
1121    </li>
1122
1123    <li>When you are distributing your code, you should include a COPYRIGHT.txt
1124    file at a top level directory in your source tree. The file should contain
1125    the detailed copyright information:
1126
1127      <ul>
1128        <li>the copyright year, ranging from the year the code is first
1129        distributed to the year the code is last distributed</li>
1130
1131        <li>the copyright statement</li>
1132
1133        <li>the owner of the code and his/her address</li>
1134      </ul>
1135
1136      <p>For example:</p>
1137      <pre>
1138!------------------------------------------------------------------------------!
1139!                                                                              !
1140! (C) Crown copyright 2005-6 Met Office. All rights reserved.                  !
1141!                                                                              !
1142! Use, duplication or disclosure of this code is subject to the restrictions   !
1143! as set forth in the contract. If no contract has been raised with this copy  !
1144! of the code, the use, duplication or disclosure of it is strictly            !
1145! prohibited. Permission to do so must first be obtained in writing from the   !
1146! Head of Numerical Modelling at the following address:                        !
1147!                                                                              !
1148! Met Office, FitzRoy Road, Exeter, Devon, EX1 3PB, United Kingdom             !
1149!                                                                              !
1150!------------------------------------------------------------------------------!
1151</pre>
1152    </li>
1153  </ul>
1154 
1155  <script type="text/javascript" src="maintain.js"></script>
1156</body>
1157</html>
Note: See TracBrowser for help on using the repository browser.