User Tools

Site Tools


dev:codingconventions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
dev:codingconventions [2016/03/16 13:10]
pseewald Added docu for new prettify
dev:codingconventions [2018/12/21 08:41] (current)
tmueller [Use existing infrastructure]
Line 1: Line 1:
 ====== Coding Conventions ====== ====== Coding Conventions ======
 +
 ===== Stick to the standard ===== ===== Stick to the standard =====
-  ​* Code enabled by default should be standard ​Fortran2003 ​[-std=f2003] + 
-  * Avoid using new OOP aspects, because compilers do not yet support them well enough. +  ​* Code enabled by default should be standard ​Fortran 2008 [-std=f2008
-  * OpenMP code should follow ​the version 3.X of the standard +  * OpenMP code should follow version 3.X of the standard 
-  * MPI should should follow ​the version ​2.X of the standard +  * MPI should should follow version ​of the standard 
-  * Extended functionality should match [[wp>​POSIX]] ​[[wp>​Linux_Standard_Base|LSB]].+  * Extended functionality should match [[wp>​POSIX]] ​and [[wp>​Linux_Standard_Base|LSB]].
  
 ===== Write explicit code ===== ===== Write explicit code =====
Line 15: Line 16:
     * INTEGER i=4.9999, i.e. i=INT(4.9999) implies i==4. Use NINT(4.9999) as appropriate.     * INTEGER i=4.9999, i.e. i=INT(4.9999) implies i==4. Use NINT(4.9999) as appropriate.
     * natom*natom,​ nrow_global*ncol_global overflows INT(KIND=4) for large simulations.     * natom*natom,​ nrow_global*ncol_global overflows INT(KIND=4) for large simulations.
 +    * always use REAL() with KIND parameter, i.e. r = REAL(i, KIND=dp).
 +    * avoid FLOAT() in favour of REAL(, KIND=dp).
     * the global number of grid points (pw_grid_type%ngpts,​ngpts_cut) overflows INT(KIND=4) for large simulations.     * the global number of grid points (pw_grid_type%ngpts,​ngpts_cut) overflows INT(KIND=4) for large simulations.
  
Line 36: Line 39:
  
 ===== Use existing infrastructure ===== ===== Use existing infrastructure =====
-For many common ​operation ​there exist wrappers in CP2K to prevent usage errors and to allow for central redirections.+ 
 +Always prefer [[https://​gcc.gnu.org/​onlinedocs/​gcc-8.2.0/​gfortran/​Intrinsic-Procedures.html|built-in (intrinsic) functions]] instead of hand-coded routines since they usually include extra numerical checks to avoid intermediate under- or overflow while still performing optimally. Examples: 
 + 
 +  * ''​NORM2(x)''​ instead of ''​%%SQRT(x(1)**2 + x(2)**2 + x(3)**2)%%''​ 
 +  * ''​DOT_PRODUCT(x,​ x)''​ instead of ''​%%x(1)**2 + x(2)**2 + x(3)**2%%''​ 
 +  * ''​DOT_PRODUCT(x,​ y)''​ instead of ''​%%x(1)*y(1) + x(2)*y(2) + x(3)*y(3)%%''​ 
 + 
 + 
 +For many common ​operations ​there exist wrappers in CP2K to prevent usage errors and to allow for central redirections, i.e. avoid to use direct calls to external libraries in CP2K 
   * Use the routines from ''​cp_files.F''​ instead of calling ''​OPEN''​ and ''​CLOSE''​ directly.   * Use the routines from ''​cp_files.F''​ instead of calling ''​OPEN''​ and ''​CLOSE''​ directly.
   * Use the routines from the full-matrix ''​fm''​-package instead of calling BLAS or Scalapack directly.   * Use the routines from the full-matrix ''​fm''​-package instead of calling BLAS or Scalapack directly.
   * Use the routines from ''​message_passing.F''​ instead of calling MPI directly.   * Use the routines from ''​message_passing.F''​ instead of calling MPI directly.
 +  * Use the routines from ''​fft_lib.F''​ instead of calling FFT (any library) directly.
   * Use the routines from ''​machine.F''​ to access architecture depended things like e.g. the working directory.   * Use the routines from ''​machine.F''​ to access architecture depended things like e.g. the working directory.
   * Don't use ''​UNIT=*''​ in ''​WRITE''​ or ''​PRINT''​ statements. Instead request a unit from the logger: ''​iw=cp_logger_get_default_unit_nr()''​ and write only if you actually received a unit: ''​IF(iw>​0) WRITE (UNIT=iw, ,,,​)''​.   * Don't use ''​UNIT=*''​ in ''​WRITE''​ or ''​PRINT''​ statements. Instead request a unit from the logger: ''​iw=cp_logger_get_default_unit_nr()''​ and write only if you actually received a unit: ''​IF(iw>​0) WRITE (UNIT=iw, ,,,​)''​.
Line 53: Line 66:
   * Each module and routine should be annotated with [[dev:​codingconventions#​Doxygen| Doxygen documentation]].   * Each module and routine should be annotated with [[dev:​codingconventions#​Doxygen| Doxygen documentation]].
   * Each preprocessor flag should start with two underscores and be documented in the ''​INSTALL''​-file and added to the cp2k_flags function (cp2k_info.F).   * Each preprocessor flag should start with two underscores and be documented in the ''​INSTALL''​-file and added to the cp2k_flags function (cp2k_info.F).
-  * The code should be formatted with the prettify-tool by running ''​make -j pretty''​. +  * The code should be formatted with the [[dev:​formattingconventions| ​prettify tool]] by running ''​make -j pretty''​.
 ===== Write tests ===== ===== Write tests =====
   * Every feature should be tested, with the goal of complete [[ http://​www.cp2k.org/​static/​coverage/​ | code coverage by regtesting ]].   * Every feature should be tested, with the goal of complete [[ http://​www.cp2k.org/​static/​coverage/​ | code coverage by regtesting ]].
Line 65: Line 77:
   * Please run ''​make doxify''​ to format your doxygen comments, or generate templates where none exist   * Please run ''​make doxify''​ to format your doxygen comments, or generate templates where none exist
   * See our [[ http://​doxygen.cp2k.org/​files.html | doxygen pages ]] for the result   * See our [[ http://​doxygen.cp2k.org/​files.html | doxygen pages ]] for the result
- 
-===== Formatting conventions and auto-formatting (prettify) ===== 
-Uniform formatting of CP2K source code will be enabled in the near future by a prettify script that is an almost complete auto-formatter for Fortran 90 source code. As a rule of thumb, developers should not worry about the format of their code and just let prettify do its magic by running ''​make -j pretty''​. The chosen formatting conventions for CP2K are as follows: 
-  * Sorting and alignment of variable declarations and ''​USE''​ statements, removal of unused list entries. 
-  * Indentation with a relative width of 3 characters. 
-  * Line continuations are aligned with the previous opening delimiter ''​('',​ ''​[''​ or ''​(/''​ or with an assignment operator ''​=''​ or ''​%%=>​%%''​. If none of the above is present, a default hanging indent of 3 characters is applied. 
-  * All operators are surrounded by exactly one whitespace character, except for arithmetic operators. 
-  * Removal of extraneous whitespace and consecutive blank lines. 
-  * Uppercase notation for all Fortran and OpenMP keywords. 
-The following formatting decisions are still manual and are never changed by prettify: 
-  * Positions of line breaks (except for variable declarations and ''​USE''​ statements). 
-  * No indentation of subsequent ''​DO''​ / ''​IF''​ statements that are aligned with each other. 
-There may be cases where manual alignment is preferred over the rules stated above. The following options for manual formatting are provided: 
-  * No automatic realignment of line continuations that are prefixed with an ''&''​. 
-  * No auto-formatting of lines to which a comment starting with ''​!&''​ is attached. 
-  * No auto-formatting of code blocks enclosed between two comment lines starting with ''​!&<''​ and ''​!&>''​. 
- 
-A few examples to illustrate how to deal with cases where auto-formatting produces unsatisfying results: 
- 
-  * Reduce hanging indent by inserting linebreaks directly after assignment operator and opening delimiter: 
-<code fortran> 
-! No: 
-long_result_var_name = long_function_name(arg_1,​ arg_2, & 
-                                          arg_3, arg_4, arg_5)+ & 
-                       foo 
-! Yes: 
-long_result_var_name = & 
-   ​long_function_name( & 
-      arg_1, arg_2, & 
-      arg_3, arg_4, arg_5)+ & 
-   foo 
-</​code>​ 
-  * Avoid linebreaks in deeply nested expressions:​ 
-<code fortran> 
-! No: 
-bessj0 = (r1+y*(r2+y*(r3+y*(r4+y* & 
-                            (r5+y*r6)))))/​(s1+y*(s2+y*(s3+y* & 
-                                                       ​(s4+y*(s5+y*s6))))) 
-! Yes: 
-bessj0 = (r1+y*(r2+y*(r3+y*(r4+y*(r5+y*r6)))))/​ & 
-         ​(s1+y*(s2+y*(s3+y*(s4+y*(s5+y*s6))))) 
-</​code>​ 
-  * Alignment by explicit bracketing: 
-<code fortran> 
-! No: 
-foo = bar+foobar(x1,​ y1, z1)* & 
-      foobar(x2, y2, z2)* & 
-      foobar(x3, y3, z3) 
-! Yes: 
-foo = bar+(foobar(x1,​ y1, z1)* & 
-           ​foobar(x2,​ y2, z2)* & 
-           ​foobar(x3,​ y3, z3)) 
-</​code>​ 
-  * Special vertical alignment may require manual formatting: 
-<code fortran> 
-! Auto-formatting:​ 
-align_me = [-1, 10, 0, & 
-            0, 1000, 0, & 
-            0, -1, 1] 
-! Manual alignment (!& disables whitespace formatting):​ 
-align_me = [-1,   10, 0, & !& 
-             0, 1000, 0, & !& 
-             ​0, ​  -1, 1] !& 
-! Alternatively:​ 
-!&< 
-align_me = [-1,   10, 0, & 
-             0, 1000, 0, & 
-             ​0, ​  -1, 1] 
-!&> 
-</​code>​ 
dev/codingconventions.1458133835.txt.gz · Last modified: 2016/03/16 13:10 by pseewald