Differences

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

--- dev:codingconventions [2016/03/16 13:10] – Added docu for new prettify pseewald
+++ dev:codingconventions [2020/08/21 10:15] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
 ====== Coding Conventions ======
 ===== 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 =====
@@ Line 15: / Line 16: @@
     * 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.
+    * 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.
 ===== Don't use poorly designed language features =====
   * Do not use the ''GOTO''-statement. See also [[http://xkcd.com/292/]] and [[doi>10.1145/362929.362947]]
-  * Do not use left-hand-side (lhs) reallocations of allocatables [-Wrealloc-lhs-all]. [[http://www.tddft.org/pipermail/octopus-devel/2012-February/005510.html | Why? ]]
+  * Do not use left-hand-side (lhs) reallocations of allocatables [-Wrealloc-lhs]. [[https://github.com/cp2k/cp2k/issues/726 | Why? ]]
   * Do not use ''FORALL'' constructs. [[https://gcc.gnu.org/ml/fortran/2012-04/msg00025.html | Why? ]]
   * Do not use ''OMP THREADPRIVATE'' variables.
@@ Line 36: / Line 39: @@
 ===== 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 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 ''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.
   * 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 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 =====
   * 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
   * 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, &
-, 1000, 0, &
-, -1, 1]
-! Manual alignment (!& disables whitespace formatting):
-align_me = [-1,   10, 0, & !&
-, 1000, 0, & !&
-,   -1, 1] !&
-! Alternatively:
-!&<
-align_me = [-1,   10, 0, &
-, 1000, 0, &
-,   -1, 1]
-!&>
-</code>