Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

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


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

Legend:

Unmodified
Added
Removed
Modified
  • code/C++_styleguide

    v14 v15  
    1111=== General ===
    1212Keep 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).
    13  and don't include header files in header files but rather in source files if you can help it.
    1413Example for class {{{MyExampleClass}}}.
    1514{{{
     
    2019
    2120=== Headers ===
    22 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.
     21Try 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.
    2322Example for a header file include sequence.
    2423{{{
     
    2625
    2726#include <string>              // std includes
    28 
    2927#include <OgrePrerequisites.h> // most external libraries have forward declaration files as well
    30 #include <OgreFrameListener.h> // only include this if you inherit from it or you don't use an object as pointer/reference
    31 
    32 #include "Projectile.h"        // our own files, if necessary
    33 }}}
    34 Note: Never ever (!!!) write {{{using namespace blah;}}} in header files! (think about what it means a little bit)
     28#include "OrxonoxClass.h"      // only include this if you inherit from it or you don't use an object as pointer/reference
     29}}}
     30Note: Never ever (!!!) write {{{using namespace foo;}}} in header files! (think about what that would mean)
    3531
    3632=== Source files ===
    37 Again, keep the dependencies short. However it is not that severe in source files.[br]
    38 To ensure that every header file can be compiled without additional header dependencies, include class header file first.
     33Again, keep the dependencies short. However it is not that severe in source files. [[br]]
     34To ensure that every header file can be compiled without additional header dependencies, include the class header file first.
    3935Include sequence is for {{{MyClass}}}:
    4036{{{
     
    4339#include <vector>              // std headers
    4440#include <map>
    45 
    4641#include <OgreSceneManager.h>  // external library headers
    47 
    4842#include "BaseObject.h"        // our own header files
    4943}}}
    5044
    5145=== Namespaces ===
    52 Create a directory for every namespace (== create a directory for every modules and all its submodules). Names representing namespaces should be all lowercase.[[br]]
     46Use namespaces for separate libraries like network, 'orxonox' otherwise. Names representing namespaces should be all lowercase.[[br]]
    5347Don'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.
    5448
    55 === Inlineing and Templates ===
    56 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).
     49=== Inlining and Templates ===
     50Inline 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]]
     51Using 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]]
     52An Example:
     53{{{
     54class FooBar
     55{
     56    void funcA()
     57        { return this->myVar_; }
     58    void funcB();
     59};
     60
     61inline void FooBar::funcB()
     62{
     63    doSomething();
     64    doOtherStuff();
     65}
     66}}}
     67
    5768
    5869=== Machine-Dependent Code ===
    5970Place machine-dependent code in a special file so that it may be easily located when porting code from one machine to another.
    6071
    61 === 80 Columns at Maximum ===
    62 File content must be kept within 80 columns.
     72=== 80 Columns tops ===
     73If you can help it, try to keep your code within 80 character columns, 120 tops otherwise. [[br]]
    6374''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.''
    6475
     
    7889Every file that contains source code must be documented with an introductory comment that provides information on the file name and its contents:
    7990{{{
    80 //
    81 }}}
     91/**
     92@file
     93@brief
     94    A brief description.
     95    More description.
     96*/
     97}}}
     98Note: 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.
    8299
    83100== Naming Conventions ==
    84101
    85102=== Classes and Types ===
    86 Names representing types must be in mixed case starting with upper case.
     103Names representing types must be in mixed case (CamelCase) starting with upper case.
    87104{{{
    88105class SavingsAccount {
     
    129146
    130147=== Constants ===
    131 Named constants (including enumeration values) must be all uppercase using underscore to separate words. Always use constants instead of numbers.
     148Named constants (including enumeration values) must be all uppercase using underscore to separate words. Always use constants instead of numbers and macros.
    132149{{{
    133150const int MAX_ITERATIONS = 5;
     
    144161For interface functions to local member variables use short functions (setter and getter functions):
    145162{{{
    146 class WorldEntity {
     163class WorldEntity
     164{
    147165public:
    148   inline string Name() {
    149     return name_;
    150   }
    151 
    152   inline void setName(const string& name) {
    153     name_ = name;
    154   }
     166    std::string getName()
     167      { return name_; }
     168
     169    void setName(const std::string& name)
     170        { name_ = name; }
    155171
    156172private:
    157   string name_;
     173    std::string name_;
    158174};
    159175}}}
     
    161177The name of the object is implicit, and should be avoided in a method name.
    162178{{{
    163 class Line {
     179class Line
     180{
    164181public:
    165   float getLength(); // Not getLineLength() since it's clear that it is a line.
     182    float getLength(); // Not getLineLength() since it's clear that it is a line.
    166183};
    167184}}}
     
    170187Enumeration constants can be prefixed by a common type name.
    171188{{{
    172 enum Color {
    173   COLOR_RED,
    174   COLOR_GREEN,
    175   COLOR_BLUE
    176 };
     189enum Color
     190{
     191    COLOR_RED,
     192    COLOR_GREEN,
     193    COLOR_BLUE
     194};
     195}}}
     196However it is better to place an enumeration in a separate namespace. Use 'Enum' as the name of the enum.
     197{{{
     198namespace Colour
     199{
     200    enum Enum
     201    {
     202        Red,
     203        Green,
     204        Blue
     205    };
     206}
    177207}}}
    178208
    179209=== Namespaces ===
    180 Names representing namespaces should be all lowercase.
    181 {{{
    182 namespace ioutil {
    183 
     210Names representing namespaces should be all lowercase and consist of one word.
     211{{{
     212namespace util
     213{
    184214}
    185215}}}
     
    188218== Indentation ==
    189219=== Spaces ===
    190 Use 2 spaces for an indentation level. Never use tabs, as it is common in windows IDEs.
     220Use 4 spaces for an indentation level. Never use tabs, as it is common in windows IDEs.
    191221
    192222=== Split Lines ===
     
    206236
    207237== Whitespaces ==
    208 Use one space after each keyword
     238Use one space after each keyword and enclose operators with 2 of them: {{{ if (a + b < c) }}}
    209239
    210240
     
    241271floatValue = float(intValue);
    242272}}}
    243 By this, the programmer indicates that he is aware of the different types involved and that the mix is intentional.
    244 
    245 
    246 === Encapsulation ===
     273By this, the programmer indicates that he is aware of the different types involved and that the mix is intentional. [[br]]
     274Note: Never, ever use static_cast or C-Style cast when dealing with multiple or virtual inheritance!
     275
     276
     277
     278=== Data Encapsulation ===
    247279Class 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.
    248280
     
    254286== Layout ==
    255287=== Indentation ===
    256 Basic indentation should be 2.
    257 {{{
    258 for (i = 0; i < numberOfElements; i++)
    259   a[i] = 0;
     288Basic indentation should be 4.
     289{{{
     290for (i = 0; i < numberOfElements; ++i)
     291    a[i] = 0;
    260292}}}
    261293
     
    264296Block layout should be as illustrated in this example:
    265297{{{
    266 while (!done) {
     298while (!done)
     299{
    267300  doSomething();
    268301  done = moreToDo();
     
    299332The if-else class of statements should have the following form:
    300333{{{
    301 if (condition) {
    302   ...
    303 }
    304 else {
    305   ...
    306 }
     334if (condition)
     335{
     336  ...
     337}
     338else
     339{
     340  ...
     341}
     342}}}
     343Never use the token below as it does not, what you expect:
     344{{{
     345if (condition1)
     346    if (condition2)
     347        doSomething();
     348else                    // This else corresponds to the second if!
     349    doSomethingElse();
    307350}}}
    308351