Coding guidelines in ORCHIDEE or how to write clean code

Author: J. Ghattas
Last revision: J. Ghattas (2023/11/24)

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 for ORCHIDEE are divided into 2 parts :

• Structuring of the code, document written by the ORCHIDEE group : ORCHIDEE_Coding_Guidelines_v1.1_2022.pdf​
• Guidelines for Fortran Programming on Heterogeneous Architectures, done by Kazem Ardaneh : ​https://hal.science/hal-04193779

The main "take home" messages from the first document 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 if it is a big loop.

• 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).

• Do not use nested WHERE loops.