wiki:Documentation/UserGuide/CodingGuidelines

Coding guidelines in ORCHIDEE or how to write clean code

Author: J. Ghattas
Last revision: B. Guenet (2020/03/19)

Coding guidelines have been established to facilitate the development of the ORCHIDEE code. All developers should follow these guidelines when improving or adding new features to the code.

Moreover, any new suggestions to these coding guide lines, in order to improve the readability, the efficiency and the robustness of the code are welcome. You can make these suggestions to the ORCHIDEE project group (orchidee-projet at listes.ipsl.fr).

Detailed guidelines must be read in coding_guidelines.pdf and coding_guidelines.doc

But the main "take home" messages are:

  • Comment your code as most as you can and make sure that it easy to understand for non specialist
  • All the comments must be in English
  • All the parameters used must be externalized (no hard-coded numbers) and the default values must be associated with a reference to identify the source of the parameter values. If tuned, please explain how and why.
  • When using loops don't forget the "ELSE" to catch any situation not covered in the other cases.
  • If you are using a SELECT CASE ... CASE ... END SELECT statement, it is recommended for the same reason that you include a “CASE default” statement at the end.
  • When defining a new variable, use a comment in the declaration part to give the unit and meaning of the variable, and make sure that the unit is coherent with the rest of the calculations
  • Although the maximum line length of FORTRAN 90 is 132 characters, try to keep your code to less than 100 characters per line - this preserves the formatting for those who work with small terminal windows on their computer and when producing a printout.
  • Do not use non-ascii characters (typically, accentuated characters) in comments. They are non portable and can induce treatment failure by code analysis scripts.
  • Take care of your indexation when using a loop and identified the statement by a comment just after your ENDIF or ENDDO.
  • Be mindful of loop ordering for best memory access (performance). If the embedded loops are independent, then the first index should correspond to the most inner loop. This ensures that one accesses contiguous memory blocks during the loop, which makes it faster (example on page 17 of coding_guidelines.pdf)
  • Test your modifications on several computers, as they use different fortran compilers. In the ORCHIDEE/arch directory, you find informations on the ccompilers used by the machines.
  • You must do some test runs with the debug option activated during compilation. To activate compile debug options for testing the code some informations are summarized here(howto).
Last modified 11 months ago Last modified on 06/02/20 06:44:57

Attachments (2)

Download all attachments as: .zip