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