Maria Haupt / gammalib

Commit b3f7d5b4b2db337dee14f66d584e9d8bde9fa019

Authored by Jürgen Knödlseder
1 parent 90b7b4f1

Add rule that forward declarations are preferred over #include directives in the header file.

Inline Side-by-side
Showing 1 changed file with 12 additions and 9 deletions
doc/source/coding/coding.rst
  View file @b3f7d5b
... ... @@ -20,10 +20,13 @@ Each class should be defined in a pair of individual files:
20 20 In addition, a SWIG interface file should be provided for the Python
21 21 bindings (with filename suffix ``.i``).
22 22  
23   -Each file should contain the ``#include`` directives that are necessary for
24   -compilation of the specific file. ``#include`` directives that are specified
25   -in the header file can be omitted in the source code file, provided that
26   -the header file is included in the source code file.
  23 +In the header file, prefer forward declarations instead of ``#include``
  24 +directives to minimise the dependencies between the files. Specify only
  25 +the ``#include`` directives that are absolutely needed to compile the
  26 +code.
  27 +
  28 +In the source file, put all ``#include`` directives that are necessary for
  29 +compilation of the specific file.
27 30  
28 31 The C++ style header files should be used instead of the C style header
29 32 files to ensure maximum portability. The following table provides the
... ... @@ -42,11 +45,11 @@ C++ C Function examples
42 45 ============= ============== =================
43 46  
44 47 Note that functions and types should be prefixed by ``std::``. For example,
45   -``cos`` becomes ``std::cos``, ``time_t`` becomes ``std::time_t``, etc. One significant
46   -change between C and C++ is that ``fabs`` becomes ``std::abs`` since the C style
47   -``abs`` function only applies to integers. Here, the ``std::`` prefix is crucial
48   -to distinguish the C++ function (which is also defined for doubles) from
49   -the C function.
  48 +``cos`` becomes ``std::cos``, ``time_t`` becomes ``std::time_t``, etc.
  49 +One significant change between C and C++ is that ``fabs`` becomes ``std::abs``
  50 +since the C style ``abs`` function only applies to integers. Here, the
  51 +``std::`` prefix is crucial to distinguish the C++ function (which is also
  52 +defined for doubles) from the C function.
50 53  
51 54 .. _sec_header:
52 55  
... ...