Merge pull request #15 from msleigh/main

Paddy's updates, and change from 'guidelines' to 'standards'

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'),
 ]
 

fortran/index.rst

@@ -1,74 +1,69 @@
-.. 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.
 
 
 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

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*

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

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
 

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'),
 ]
 

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