Context Navigation

Changes between Version 14 and Version 15 of code/C++_styleguide

Timestamp:: Sep 4, 2008, 7:06:28 PM (16 years ago)
Author:: rgrieder
Comment:: —

Legend:

: Unmodified
: Added
: Removed
: Modified

code/C++_styleguide

-                      v14
+                      v15
 === General ===
 Keep your classes/files short, don't exceed 2000 LOC (if it get's longer you may separate functions into different modules). Put every class in a separate file and name the file like the class name (use !CamelCase names). Create a separate header (ends with .h) and source file (ends with .cc).
- and don't include header files in header files but rather in source files if you can help it.
 Example for class {{{MyExampleClass}}}.
 {{{
 …
 === Headers ===
 Keep your include dependencies in header files as little as possible. Whenever a class member is just a pointer or reference, the forward declaration is sufficient. To make that easier there exists a prerequisites file for each library, containing all the necessary forward declarations. These have to be kept up to date of course.
+Try to minimize header file dependencies by making use of forward declaration and careful dependency studies. Whenever a class member is just a pointer or reference, the forward declaration is sufficient. To make that easier there exists a prerequisites file for each library, containing all the necessary forward declarations. These have to be kept up to date of course.
 Example for a header file include sequence.
 {{{
 …
 #include <string>              // std includes
 #include <OgrePrerequisites.h> // most external libraries have forward declaration files as well
+#include <OgreFrameListener.h> // only include this if you inherit from it or you don't use an object as pointer/reference
+#include "Projectile.h"        // our own files, if necessary
+}}}
+Note: Never ever (!!!) write {{{using namespace blah;}}} in header files! (think about what it means a little bit)
+#include "OrxonoxClass.h"      // only include this if you inherit from it or you don't use an object as pointer/reference
+}}}
+Note: Never ever (!!!) write {{{using namespace foo;}}} in header files! (think about what that would mean)
 === Source files ===
 Again, keep the dependencies short. However it is not that severe in source files.[br]
 To ensure that every header file can be compiled without additional header dependencies, include class header file first.
+Again, keep the dependencies short. However it is not that severe in source files. [[br]]
+To ensure that every header file can be compiled without additional header dependencies, include the class header file first.
 Include sequence is for {{{MyClass}}}:
 {{{
 …
 #include <vector>              // std headers
 #include <map>
 #include <OgreSceneManager.h>  // external library headers
 #include "BaseObject.h"        // our own header files
 }}}
 === Namespaces ===
 Create a directory for every namespace (== create a directory for every modules and all its submodules). Names representing namespaces should be all lowercase.[[br]]
+Use namespaces for separate libraries like network, 'orxonox' otherwise. Names representing namespaces should be all lowercase.[[br]]
 Don't write "using namespace ..;" in header files because otherwise if someone included that header file, the "using namespace .." would automatically be included as well. That may lead to unwanted errors.
+=== Inlineing and Templates ===
+Inline functions and template structures should be declared in a .h header file as described above but implemented in a *-inl.h file (since templates are normally not implemented in a source .cc file).
+=== Inlining and Templates ===
+Inline functions and template structures should be declared in a .h header file as described above and implemented below the class declaration if the definition exceeds one line. [[br]]
+Using the 'inline' keyword within the class declaration doesn't give advantages (it's inline anyway), so let it be. It is necessary outside however. [[br]]
+An Example:
+{{{
+class FooBar
+{
+    void funcA()
+        { return this->myVar_; }
+    void funcB();
+};
+inline void FooBar::funcB()
+{
+    doSomething();
+    doOtherStuff();
+}
+}}}
 === Machine-Dependent Code ===
 Place machine-dependent code in a special file so that it may be easily located when porting code from one machine to another.
 === 80 Columns at Maximum ===
+File content must be kept within 80 columns.
+=== 80 Columns tops ===
+If you can help it, try to keep your code within 80 character columns, 120 tops otherwise. [[br]]
 ''Comment: 80 columns is a common dimension for editors, terminal emulators, printers and debuggers, and files that are shared between several people should keep within these constraints. It improves readability when unintentional line breaks are avoided when passing a file between programmers.''
 …
 Every file that contains source code must be documented with an introductory comment that provides information on the file name and its contents:
 {{{
+//
+}}}
+/**
+@file
+@brief
+    A brief description.
+    More description.
+*/
+}}}
+Note: try not to fill in the filename. It is obvious and the comment compiler (Doxygen) will do it automatically and you don't have to adjust it when renaming the file.
 == Naming Conventions ==
 === Classes and Types ===
 Names representing types must be in mixed case starting with upper case.
+Names representing types must be in mixed case (CamelCase) starting with upper case.
 {{{
 class SavingsAccount {
 …
 === Constants ===
 Named constants (including enumeration values) must be all uppercase using underscore to separate words. Always use constants instead of numbers.
+Named constants (including enumeration values) must be all uppercase using underscore to separate words. Always use constants instead of numbers and macros.
 {{{
 const int MAX_ITERATIONS = 5;
 …
 For interface functions to local member variables use short functions (setter and getter functions):
 {{{
+class WorldEntity {
+class WorldEntity
+{
 public:
+  inline string Name() {
+    return name_;
+  }
+  inline void setName(const string& name) {
+    name_ = name;
+  }
+    std::string getName()
+      { return name_; }
+    void setName(const std::string& name)
+        { name_ = name; }
 private:
   string name_;
+    std::string name_;
 };
 }}}
 …
 The name of the object is implicit, and should be avoided in a method name.
 {{{
+class Line {
+class Line
+{
 public:
   float getLength(); // Not getLineLength() since it's clear that it is a line.
+    float getLength(); // Not getLineLength() since it's clear that it is a line.
 };
 }}}
 …
 Enumeration constants can be prefixed by a common type name.
 {{{
+enum Color {
+  COLOR_RED,
+  COLOR_GREEN,
+  COLOR_BLUE
+};
+enum Color
+{
+    COLOR_RED,
+    COLOR_GREEN,
+    COLOR_BLUE
+};
+}}}
+However it is better to place an enumeration in a separate namespace. Use 'Enum' as the name of the enum.
+{{{
+namespace Colour
+{
+    enum Enum
+    {
+        Red,
+        Green,
+        Blue
+    };
+}
 }}}
 === Namespaces ===
 Names representing namespaces should be all lowercase.
 {{{
 namespace ioutil {
+Names representing namespaces should be all lowercase and consist of one word.
+{{{
+namespace util
+{
+}
 }}}
 …
 == Indentation ==
 === Spaces ===
 Use 2 spaces for an indentation level. Never use tabs, as it is common in windows IDEs.
+Use 4 spaces for an indentation level. Never use tabs, as it is common in windows IDEs.
 === Split Lines ===
 …
 == Whitespaces ==
 Use one space after each keyword
+Use one space after each keyword and enclose operators with 2 of them: {{{ if (a + b < c) }}}
 …
 floatValue = float(intValue);
 }}}
+By this, the programmer indicates that he is aware of the different types involved and that the mix is intentional.
+=== Encapsulation ===
+By this, the programmer indicates that he is aware of the different types involved and that the mix is intentional. [[br]]
+Note: Never, ever use static_cast or C-Style cast when dealing with multiple or virtual inheritance!
+=== Data Encapsulation ===
 Class variables should never be declared public. The concept of C++ information hiding and encapsulation is violated by public variables. Use private variables and access functions instead. One exception to this rule is when the class is essentially a data structure, with no behavior (equivalent to a C struct). In this case it is appropriate to make the class' instance variables public.
 …
 == Layout ==
 === Indentation ===
 Basic indentation should be 2.
 {{{
 for (i = 0; i < numberOfElements; i++)
   a[i] = 0;
+Basic indentation should be 4.
+{{{
+for (i = 0; i < numberOfElements; ++i)
+    a[i] = 0;
 }}}
 …
 Block layout should be as illustrated in this example:
 {{{
+while (!done) {
+while (!done)
+{
   doSomething();
   done = moreToDo();
 …
 The if-else class of statements should have the following form:
 {{{
+if (condition) {
+  ...
+}
+else {
+  ...
+}
+if (condition)
+{
+  ...
+}
+else
+{
+  ...
+}
+}}}
+Never use the token below as it does not, what you expect:
+{{{
+if (condition1)
+    if (condition2)
+        doSomething();
+else                    // This else corresponds to the second if!
+    doSomethingElse();
 }}}