Developer Docs: Include Guide (#874)

Following these include guides will allow us to catch bugs,
e.g. missing includes, early and will avoid problems when using
package managers.

1 files changed, 18 insertions, 1 deletions

diff --git a/Docs/source/developers/repo_organization.rst b/Docs/source/developers/repo_organization.rst
index 495cc8fc7..5bc6e65b3 100644
--- a/Docs/source/developers/repo_organization.rst
+++ b/Docs/source/developers/repo_organization.rst
@@ -16,7 +16,24 @@ The main WarpX class is WarpX, implemented in ``Source/WarpX.cpp``.
 Build system
 ------------
 
-WarpX uses the AMReX build system. Each sub-folder contains a file ``Make.package`` with the names of header files and source files to include for the build.
+WarpX uses the AMReX build system (GNUMake).
+Each sub-folder contains a file ``Make.package`` with the names of source files (``.cpp``) that are added to the build.
+Do not list header files (``.H``) here.
+
+C++ Includes
+------------
+
+All WarpX header files need to be specified relative to the ``Source/`` directory.
+
+- e.g. ``#include "Utils/WarpXConst.H"``
+- files in the same directory as the including header-file can be included with ``#include "FileName.H"``
+
+The `include order <https://github.com/ECP-WarpX/WarpX/pull/874#issuecomment-607038803>`_ and `proper quotation marks <https://gcc.gnu.org/onlinedocs/cpp/Include-Syntax.html>`_ are:
+
+1. WarpX header files ``#include "..."`` then
+2. AMReX header files ``#include <...>`` then
+3. other third party includes ``#include <...>`` then
+4. standard library includes, e.g. ``#include <vector>``
 
 WarpX-specific vocabulary
 -------------------------