Changes between Version 34 and Version 35 of Coding_Conventions

Timestamp:

Mar 20, 2018, 9:59:45 PM (6 years ago)

Author:

Itms

Comment:

Update year and specify include order convention

Coding_Conventions

@@ -21 +21 @@
 {{{
 #!cpp
-/* Copyright (C) 2017 Wildfire Games.
+/* Copyright (C) 2018 Wildfire Games.
  * This file is part of 0 A.D.
  *
@@ -38 +38 @@
  */
 }}}
-   replacing `2017` with the year that the file was last updated.
+   replacing `2018` with the year that the file was last updated.
 
   '' Exception:''  Code in `source/lib/`  (and a few other files) should use the MIT license instead:
 {{{
 #!cpp
-/* Copyright (C) 2017 Wildfire Games.
+/* Copyright (C) 2018 Wildfire Games.
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -77 +77 @@
  * All source files must have the `svn:eol-style` property set to `native`
 
- * The first non-comment line of any source file must be `#include "precompiled.h"`
-
 === Formatting ===
  * Use tabs for indentation, not spaces.
@@ -208 +206 @@
 }}}
 
+=== Preprocessor instructions ===
+
+The `#include` instructions, placed after the license notice, should follow a consistent order (which is currently not the case). Between each section in the following list, we usually add an empty line.
+
+1. The first non-comment line of **any** source file **must** be `#include "precompiled.h"`
+1. For `.cpp` files that contain function implementations, headers that declare those functions should be included here. For instance, `#include "Simulation2.h"` for `Simulation2.cpp`, or `#include "ICmpPosition.h"` for `CCmpPosition.cpp`.
+1. Include the files that come from the same folder. Do not write the complete path relative to `source/`, but rather the file name only. Use case-insensitive alphabetical order.
+1. Include the files that come from the same project, but a different folder (even subdirectories of the current file's directory). Write the complete path relative to `source/`, for instance `#include "simulation2/Simulation2.h"`. Use case-insensitive alphabetical order.
+1. Include the files that come from other projects. Write the complete path relative to `source/`, for instance `#include "lib/file/file.h"`. Use case-insensitive alphabetical order.
+1. Include system libraries, in case-insensitive alphabetical order.
+
+Example, for the file `source/simulation2/Simulation2.cpp` (this is not the actual list, but an example that should cover all cases):
+
+{{{
+#include "precompiled.h"
+
+#include "Simulation2.h"
+
+#include "Example.h"
+#include "MessageTypes.h"
+
+#include "simulation2/components/ICmpAIManager.h"
+#include "simulation2/components/ICmpCommandQueue.h"
+#include "simulation2/components/ICmpTemplateManager.h"
+#include "simulation2/system/ComponentManager.h"
+#include "simulation2/system/ParamNode.h"
+
+#include "graphics/Terrain.h"
+#include "lib/file/vfs/vfs_util.h"
+#include "lib/timer.h"
+#include "maths/MathUtil.h"
+#include "ps/Loader.h"
+#include "ps/lowercase.h"
+#include "ps/Profile.h"
+#include "ps/XML/Xeromyces.h"
+#include "scriptinterface/ScriptInterface.h"
+#include "scriptinterface/ScriptRuntime.h"
+
+#include <iomanip>
+#include <string>
+}}}
+
 === Misc ===
  * In header files, avoid `#include` and use forward declarations wherever possible.
-
- * Sometimes it's nice to put `#include`s in alphabetical order. (It's a bit prettier, and makes it easier to find if some header is already in the list or not.) (But when `Foo.cpp` includes `Foo.h`, that should usually go before every other include (except for `precompiled.h` which must always be first).)
 
  * Class names are !UpperCamelCase and prefixed with `C`, e.g. `CGameObject`. Member functions are !UpperCamelCase, e.g. `CGameObject::SetModifiedFlag(...)`. Member variables are !UpperCamelCase prefixed with `m_`, e.g. `CGameObject::m_ModifiedFlag`. Files are named e.g. `GameObject.cpp`, `GameObject.h`, usually with one major class per file (possibly with some other support classes in the same files). Local variables and function parameters are lowerCamelCase. Structs are treated similarly to classes but prefixed with `S`, e.g. `SOverlayLine`.