HowTo: LMDZ code guidelines - Historique des versions

Lfairhead le 23 janvier 2025 à 11:50

2025-01-23T11:50:13Z

Abarral le 1 août 2024 à 07:17

2024-08-01T07:17:30Z

Abarral le 1 août 2024 à 07:15

2024-08-01T07:15:52Z

Abarral : Add examples of "bad" practices

2024-08-01T07:13:54Z

Add examples of "bad" practices

Abarral le 1 août 2024 à 03:46

2024-08-01T03:46:52Z

Abarral le 1 août 2024 à 03:38

2024-08-01T03:38:22Z

Abarral le 1 août 2024 à 03:30

2024-08-01T03:30:26Z

Abarral le 24 juillet 2024 à 15:47

2024-07-24T15:47:43Z

Abarral le 24 juillet 2024 à 15:46

2024-07-24T15:46:58Z

Abarral le 18 juillet 2024 à 11:17

2024-07-18T11:17:02Z

← Version précédente		Version du 23 janvier 2025 à 11:50
Ligne 2 :		Ligne 2 :

	''Note: this documents draws from various sources, including [http://broken.link.todo.replace the OPA guidelines], [https://fortranwiki.org/fortran/show/Modernizing+Old+Fortran Modernizing Old Fortran], [http://pages.swcp.com/~walt/F/F_bnf.html F syntax rules], [https://github.com/fortran-lang/stdlib/blob/master/STYLE_GUIDE.md the stdlib style guide], [https://github.com/codee-com/fortran-modernization CODEE Fortran recommendations].		''Note: this documents draws from various sources, including [http://broken.link.todo.replace the OPA guidelines], [https://fortranwiki.org/fortran/show/Modernizing+Old+Fortran Modernizing Old Fortran], [http://pages.swcp.com/~walt/F/F_bnf.html F syntax rules], [https://github.com/fortran-lang/stdlib/blob/master/STYLE_GUIDE.md the stdlib style guide], [https://github.com/codee-com/fortran-modernization CODEE Fortran recommendations].
		+
		+	== Code guidelines and conventions ==
		+
		+	=== Generalities ===
		+
		+	* fortran keywords in fortran files will be in UPPER case
		+
		+	=== Naming of modules ===
		+
		+	Module names should have a '''lmdz_''' prefix. For example, the file '''lmdz_wave.F90''' would be a module containing one or more subroutines:
		+
		+	<syntaxhighlight lang="fortran" line>
		+	MODULE lmdz_wave
		+	IMPLICIT NONE
		+
		+	CONTAINS
		+
		+	SUBROUTINE wave_init (...)
		+	...
		+	END SUBROUTINE wave_init
		+
		+	SUBROUTINE wave_calc (...)
		+	...
		+	END SUBROUTINE wave_calc
		+
		+	END MODULE lmdz_wave
		+	</syntaxhighlight>
		+

	== Example code ==		== Example code ==

@@ Ligne 129 : / Ligne 129 : @@
 Limit the use of <code>include</code> headers to the bare minimum. Whenever not possible, wrap those include in a module, and import that module instead. This provides much more flexibility, e.g. when using <code>ONLY: ...</code>.
-== Recent examples of "bad"/perfectible LMDZ code ==
+== Recent examples of improper LMDZ code ==
-''Note: The purpose of this section is '''obviously not''' to blame anyone, but to stress that "bad" code in LMDZ isn't limited to old legacy code, and that even current code is being written in a way that can be greatly improved.''
+''Note: The purpose of this section is '''obviously not''' to blame anyone, but to stress that "bad"/perfectible code in LMDZ isn't limited to old legacy code, and that even current code is being written in a way that can be greatly improved.''
 ==== 07/24: Unhelpful comment ====

@@ Ligne 245 : / Ligne 245 : @@
 As a result, there are in a lot of places such comments, many dating from 20+ years ago, for which we have no clue whether we can remove them or not. This greatly hinders readability and maintainability.
-Of course, in ''some'' cases, it is warranted to keep some code at hand, e.g. for diagnostic purpose. In such case, please '''make sure to always clearly document why the code was commented out''', so that it can be cleaned up at a later date when it becomes irrelevant.
+Of course, in ''some'' cases, it is warranted to keep some code at hand, e.g. for diagnostic purpose. In such case, please '''make sure to always clearly document ''why, when and by whom'' the code was commented out''', so that it can be cleaned up at a later date when it becomes irrelevant.
 == Questions à élucider ==

@@ Ligne 128 : / Ligne 128 : @@
 Limit the use of <code>include</code> headers to the bare minimum. Whenever not possible, wrap those include in a module, and import that module instead. This provides much more flexibility, e.g. when using <code>ONLY: ...</code>.
 == Questions à élucider ==
@@ Ligne 133 : / Ligne 251 : @@
 * Prescrit-on une langue (Français / Anglais) ?
 * Longueur des lignes: dans la limite du raisonable, pourquoi se limiter à 100-140 chars ? Le wrapping fonctionne très bien.

@@ Ligne 1 : / Ligne 1 : @@
    /!\ This page is a WORK IN PROGRESS. Nothing in this page should be considered correct or consensual for now. /!\
-''Note: this documents draws from various sources, including [http://broken.link.todo.replace the OPA guidelines].
+''Note: this documents draws from various sources, including [http://broken.link.todo.replace the OPA guidelines], [https://fortranwiki.org/fortran/show/Modernizing+Old+Fortran Modernizing Old Fortran], [http://pages.swcp.com/~walt/F/F_bnf.html F syntax rules], [https://github.com/fortran-lang/stdlib/blob/master/STYLE_GUIDE.md the stdlib style guide], [https://github.com/codee-com/fortran-modernization CODEE Fortran recommendations].
 == Example code ==

@@ Ligne 36 : / Ligne 36 : @@
 CONTAINS
-  !! Put at least a blank line before/after each function/subroutine
+  !! Put at least a blank line before/after each function/subroutine2
    SUBROUTINE my_subroutine(arg1, arg2, arg3) ! handle event xxxx
    !!                            ^ comments should always be right before, or on the same line as what they're commenting
@@ Ligne 62 : / Ligne 63 : @@
 </syntaxhighlight>
-Some comments:
+Documentation consists of putting information both inside and outside the source code. On large, formal projects, most of the documentation is outside the source code. However because the internal documentation is most closely associated with the code, it is the part most likely to remain correct as the code is modified. The thing to be really careful with is that misleading comments are even worse than having no comments at all. So, please report any misleading comments you found.
-* Limit '''to the bare minimum''' the use of preprocessor <code>#ifdef</code> keys. Those decrease lisibility, disable automatic code analysis, and generally make code a pain to manage and read. Ideally, a given preprocessor key should be used only once, or if not possible, in a single module for the entire codebase.
-* Limit the use of <code>include</code> headers to the bare minimum. Whenever not possible, wrap those include in a module, and import that module instead. This provides much more flexibility, e.g. when using <code>ONLY: ...</code>.
+Try to avoid having superfluous comments such as: <code>A = A + 1 ! Increment A by one.</code> This is not adding anything that is not immediately obvious. A person looking through your code should only have to scan your comments to be able to get a good idea of what the code does and where to look for any special activity.
 == Misc ==
@@ Ligne 113 : / Ligne 121 : @@
 * <code>DATA</code> and <code>BLOCK DATA</code> should be replaced by initializers.
 == Questions à élucider ==

@@ Ligne 16 : / Ligne 16 : @@
 ! ----------------------------------
-!! Unless specified otherwise, all files should contain a single module which encapsulates all their content
+!! Unless specified otherwise, all files should contain a single module with the same name which encapsulates all their content
 MODULE lmdz_mymodule
 !!  ^ all Fortran keywords are in CAPS, everything else is in lowercase.