diff --git a/fortran/conf.py b/fortran/conf.py index f57dc72..0f31222 100644 --- a/fortran/conf.py +++ b/fortran/conf.py @@ -19,7 +19,7 @@ # -- Project information ----------------------------------------------------- -project = 'IFS_coding_guidelines' +project = 'IFS Fortran standard' copyright = '2024-, ECMWF, Meteo-France' author = 'ECMWF' @@ -104,7 +104,7 @@ # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. -htmlhelp_basename = 'IFS_coding_guidelinesdoc' +htmlhelp_basename = 'IFS_coding_standarddoc' # -- Options for LaTeX output ------------------------------------------------ @@ -131,7 +131,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'IFS_coding_guidelines.tex', 'IFS\\_coding\\_guidelines Documentation', + (master_doc, 'IFS_coding_standard.tex', 'IFS\\_coding\\_standard Documentation', 'ECMWF', 'manual'), ] @@ -141,7 +141,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'ifs_coding_guidelines', 'IFS_coding_guidelines Documentation', + (master_doc, 'ifs_coding_standard', 'IFS_coding_standard Documentation', [author], 1) ] @@ -152,8 +152,8 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'IFS_coding_guidelines', 'IFS_coding_guidelines Documentation', - author, 'IFS_coding_guidelines', 'One line description of project.', + (master_doc, 'IFS_coding_standard', 'IFS_coding_standard Documentation', + author, 'IFS_coding_standard', 'One line description of project.', 'Miscellaneous'), ] diff --git a/fortran/index.rst b/fortran/index.rst index 577efbc..362e72c 100644 --- a/fortran/index.rst +++ b/fortran/index.rst @@ -1,64 +1,59 @@ -.. IFS_coding_guidelines documentation master file, created by - sphinx-quickstart on Wed Aug 31 09:39:39 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +Welcome to the Arpege/IFS coding standard! +========================================== -Welcome to the Arpege/IFS coding guidelines! -============================================ - -Developments to the Arpege/IFS codebase should aim to adhere to the guidelines +Developments to the Arpege/IFS codebase should aim to adhere to the standards and rules presented in this document. -Guidelines and rules described here are designed to make code easier to read, -easier to maintain, easier to extend, and less prone to bugs. -The code review process for submissions to Arpege and IFS could aim to check -code against these guidelines. +Standards and rules described here are designed to make code easier to read, +easier to maintain, easier to extend, and less prone to bugs. +The code review process for submissions to Arpege and IFS should aim to check +code against these standards. Rules are also written so as to allow implementation of automatic checking. Guidelines and recommendations ------------------------------ -* Good code should not require large amounts of comments to be intelligible. +* Good code should not require large amounts of comments to be intelligible. Nevertheless targeted explanations of particular segments of interest are desirable. Each source file should have a homogeneous coding style. * Contours of a routine or module should be considered with care, avoiding excessive length or complexity. -* Routine call signatures or interfaces should be designed with care, respecting library - contouring. Interfaces that are not internal to a component should privilege as much as +* Routine call signatures or interfaces should be designed with care, respecting library + contouring. Interfaces that are not internal to a component should privilege as much as possible native fortran datatypes rather than derived types. -* Naming of new variables, routines and modules should help the reader understand code as efficiently +* Naming of new variables, routines and modules should help the reader understand code as efficiently as possible. *Renaming of legacy / existing code?* -* Large arrays should be declared as allocatable, to avoid excessive stack usage. - Small arrays, and in particular those declared in tight code (this should be avoided wherever +* Large arrays should be declared as allocatable, to avoid excessive stack usage. + Small arrays, and in particular those declared in tight code (this should be avoided wherever possible!) should be automatic, to benefit from faster stack handling. -* If an allocatable variable can be used rather than a pointer, opt for the allocatable for +* If an allocatable variable can be used rather than a pointer, opt for the allocatable for safety reasons. -* In order to make domain decomposition easier to follow, global variable names are suffixed by G, +* In order to make domain decomposition easier to follow, global variable names are suffixed by G, while subdomain-local variables are suffixed by L. -* Different meteorological data formats are used at ECMWF and Meteo-France. - The choice between these formats should be based on logical keys LARPEGEF or LARPEGEF_xx +* Different meteorological data formats are used at ECMWF and Meteo-France. + The choice between these formats should be based on logical keys LARPEGEF or LARPEGEF_xx (and not LECMWF). -* Aladin routines that are counterparts of IFS/Arpege ones should have the same name but - prefixed with E. +* Aladin routines that are counterparts of IFS/Arpege ones should have the same name but + prefixed with E. Aladin counterparts to IFS/Arpege SUxxx setup routines should be named SUE. * Output that should appear in the main text output file should be written to NULOUT. - Output to NULOUT must be deterministic and should not change according to the - parallel distribution or the time at which the job is run. + Output to NULOUT must be deterministic and should not change according to the + parallel distribution or the time at which the job is run. Error messages should be written to unit NULERR. -* Conditional clauses with multiple cases should be handled with SELECT CASE rather than IF +* Conditional clauses with multiple cases should be handled with SELECT CASE rather than IF statements followed by multiple ELSEIF statements. -* If execution is to be aborted by the code, a call to ABOR1, with a meaningful message, +* If execution is to be aborted by the code, a call to ABOR1, with a meaningful message, should be used. @@ -66,9 +61,9 @@ Rules (as checked by norms checker) ----------------------------------- Some of the rules relate to the idea of Single Column code, where algorithmic tasks can be expressed -independently of horizontal position, and no horizontal dependencies exist. Code which maps to this +independently of horizontal position, and no horizontal dependencies exist. Code which maps to this concept can be modified at compile time by tooling (Loki, Fxtran) in line with architecture-specific -requirements. Such tooling relies heavily on code formatting to determine required transformations, +requirements. Such tooling relies heavily on code formatting to determine required transformations, explaining the prescriptive rules for these areas of code. Rules are organised into general language rules (Lw), IFS-specific rules (Ix), stylistic diff --git a/fortran/rules/I1.rst b/fortran/rules/I1.rst index 245664a..8988e73 100644 --- a/fortran/rules/I1.rst +++ b/fortran/rules/I1.rst @@ -28,7 +28,7 @@ Variable naming Routine naming ============== -* setup routines should start with subroutines +* setup routines should start with "su" * TL and AD routines should end with tl and ad respectively *Module naming* diff --git a/fortran/rules/S3.rst b/fortran/rules/S3.rst index 36b9d8b..d316cf9 100644 --- a/fortran/rules/S3.rst +++ b/fortran/rules/S3.rst @@ -1,7 +1,7 @@ S3 : line continuation ************************ -Optional arguments to a routine shall be after non-optional ones. +Line continuation should use an ampersand both at the end of lines to be continued and at the start of the next line. .. code-block:: fortran :caption: Good line continuation diff --git a/fortran/rules/S4.rst b/fortran/rules/S4.rst index 5a108fb..6717945 100644 --- a/fortran/rules/S4.rst +++ b/fortran/rules/S4.rst @@ -4,14 +4,16 @@ S4: no unqualified END statements END statements shall all be qualified. END SUBROUTINE shall state subroutine name. -To be avoided : +Correct use of end statement : .. code-block:: fortran - :caption: declaration order + :caption: end statements - SUBROUTINE WRONG_ORDER( ARG3, ARG2, ARG1) + SUBROUTINE SOME_SUBROUTINE( ARG1, ARG2, ARG3) - INTEGER(KIND=JPIM), INTENT(IN) :: ARG3 + INTEGER(KIND=JPIM), INTENT(IN) :: ARG1 INTEGER(KIND=JPIM), INTENT(IN) :: ARG2 - INTEGER(KIND=JPIM), INTENT(OUT) :: ARG1 + INTEGER(KIND=JPIM), INTENT(OUT) :: ARG3 + + END SUBROUTINE SOME_SUBROUTINE diff --git a/python/conf.py b/python/conf.py index 34fbe71..418bda7 100644 --- a/python/conf.py +++ b/python/conf.py @@ -19,7 +19,7 @@ # -- Project information ----------------------------------------------------- -project = 'IFS_python_guidelines' +project = 'IFS Python Standard' copyright = '2024-, ECMWF' author = 'ECMWF' @@ -104,7 +104,7 @@ # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. -htmlhelp_basename = 'IFS_python_guidelinesdoc' +htmlhelp_basename = 'IFS_python_standarddoc' # -- Options for LaTeX output ------------------------------------------------ @@ -131,7 +131,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'IFS_python_guidelines.tex', 'IFS\\_pythnon\_guidelines Documentation', + (master_doc, 'IFS_python_standard.tex', 'IFS\\_python\_standard Documentation', 'ECMWF', 'manual'), ] @@ -141,7 +141,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'ifs_python_guidelines', 'IFS_python_guidelines Documentation', + (master_doc, 'ifs_python_standard', 'IFS_python_standard Documentation', [author], 1) ] @@ -152,8 +152,8 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'IFS_coding_guidelines', 'IFS_coding_guidelines Documentation', - author, 'IFS_coding_guidelines', 'One line description of project.', + (master_doc, 'IFS_coding_standard', 'IFS_coding_standard Documentation', + author, 'IFS_coding_standard', 'One line description of project.', 'Miscellaneous'), ] diff --git a/python/index.rst b/python/index.rst index eb1937f..e2ff2bf 100644 --- a/python/index.rst +++ b/python/index.rst @@ -1,18 +1,13 @@ -.. IFS_coding_guidelines documentation master file, created by - sphinx-quickstart on Wed Aug 31 09:39:39 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Welcome to the IFS Python standard! -============================================ +=================================== -Developments to the IFS codebase should aim to adhere to the guidelines +Developments to the IFS codebase should aim to adhere to the standards and rules presented in this document. -Guidelines and rules described here are designed to make code easier to read, +Standards and rules described here are designed to make code easier to read, easier to maintain, easier to extend, and less prone to bugs. -The code review process for submissions to IFS could aim to check -code against these guidelines. +The code review process for submissions to IFS should aim to check +code against these standards. Rules are also written so as to allow implementation of automatic checking. Guidelines and recommendations