Changes between Version 2 and Version 3 of Coding_Conventions

Timestamp:

Jun 24, 2009, 1:05:01 AM (15 years ago)

Author:

Philip Taylor

Comment:

simplified correcter guidelines

Coding_Conventions

@@ +1 @@
+(Note: This document is aimed at C++ code. We should write something similar for JS.)
+
+== Introduction ==
+
+The goal of these coding conventions is to encourage consistency within the code, rather than claiming some particular style is better than any other. As such, the main guideline is:
+ * When modifying a piece of code, try to follow its existing style.
+Our code is currently self-inconsistent in places, but the following guidelines attempt to describe the most common style and are what we should converge towards. Obviously we want clean, readable, adequately-documented code - lots of articles and books already talk about how to do that - so we mostly describe boring typographic details.
+
+== Brief guidelines ==
+
+ * All source files (.cpp, .h) must start with the following header, before any other content:
+{{{
+/* Copyright (C) 2009 Wildfire Games.
+ * This file is part of 0 A.D.
+ *
+ * 0 A.D. is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * 0 A.D. is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with 0 A.D.  If not, see <http://www.gnu.org/licenses/>.
+ */
+}}}
+replacing `2009` with the year that the file was last updated.
+
+ * Wrap header files in include guards, using the name `INCLUDED_`''filename'', e.g. the file `Foo.h` should say:
+{{{
+#ifndef INCLUDED_FOO
+#define INCLUDED_FOO
+...
+#endif // INCLUDED_FOO
+}}}
+
+ * The first non-comment line of any source file must be `#include "precompiled.h"`
+
+ * In header files, avoid `#include` and use forward declarations wherever possible.
+
+ * Use tabs for indentation, not spaces.
+
+ * Indent braces like
+{{{
+int CExampleObject::DoSomething(int value)
+{
+    if (value != 0)
+    {
+        Prepare();
+        m_Value = value;
+    }
+    return value;
+}
+}}}
+
+ * Class names are !CamelCase and prefixed with `C`, e.g. `CGameObject`. Member functions are !CamelCase, e.g. `CGameObject::SetModifiedFlag(...)`. Member variables are !CamelCase prefixed with `m_`, e.g. `CGameObject::m_ModifiedFlag`. Files are named `GameObject.cpp`, `GameObject.h`, usually with one major class per file (possibly with some other support classes in the same files).
+
+ * Use [http://www.cppdoc.com/ CppDoc] comments, e.g.
+{{{
+class CExampleObject
+{
+    /**
+     * Sets the object's current value to the passed value, if it's non-zero.
+     *
+     * @param v the new value to set it to, or 0 to do nothing.
+     *
+     * @return the value that was passed in.
+     */
+    int DoSomething(int v);
+};
+}}}
+
+ * Use `CStr` instead of `std::string`. Use `CStrW` instead of `std::wstring`.
+
+ * Use STL when appropriate.
+
+ * ...
+
+= Old document =
+
+''The following content might be somewhat incorrect or outdated, but it's preserved here since it contains some useful information.''
+
 == Objective ==