CP2K Open Source Molecular Dynamics

User Tools

Site Tools

Trace:
dev:codingconventions

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Next revisionBoth sides next revision
dev:codingconventions [2016/03/16 13:10] – Added docu for new prettify pseewalddev:codingconventions [2020/02/11 12:00] – oschuett
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] and C99 [-std=c99] 
-  * 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 3 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.txt · Last modified: 2020/08/21 10:15 by 127.0.0.1