Changes between Version 8 and Version 9 of CppCodingStandards


Ignore:
Timestamp:
Jul 21, 2009, 7:01:14 PM (10 years ago)
Author:
dtodd
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CppCodingStandards

    v8 v9  
    4848  * ''C++ Templates: The Complete Guide'', by David Vandevoorde and Nicolai M. Josuttis
    4949
    50 == Proposed Standard ==
     50== Proposed C++ coding Standard ==
     51
     52TOPICS TO BE INCLUDED
     53
     54  * Preamble
     55  * Introduction
     56  * Curly bracket conventions and placement, i.e "{ }"
     57  * Tab locations and size conventions
     58  * Scoping of class attributes (e.g. only private class attributes, public for structures)
     59  * Naming Conventions (general, and in detail)
     60  * Misc: One declaration at a time, always 'spell out' boolean equality, use header file protection, use const as much as possible, keep scope on variables as low as possible, if ( isGood == true ) vs. if(isGood==true).
     61
     62=== Preamble ===
    5163
    5264As mentioned above, some of this was borrowed from, http://www.possibility.com/Cpp/CppCodingStandard.html, with permission as described here, "If you want to make a local copy of this standard and use it as your own you are perfectly free to do so. That's why I made it! If you find any errors or make any improvements please let me know at tmh@possibility.com."  See also http://www.possibility.com/Tmh and http://www.possibility.com/epowiki/Wiki.jsp.
     
    7991  * Standards can be used as a reason for NIH syndrome(not invented here), because the new/borrowed code won't follow the standard.
    8092
     93=== Curly bracket conventions ===
     94
     95In Brief:
     96
     97{{{
     98class Foobar  // should really be Fubar !!
     99{
     100public:
     101    Foobar(int foo, double bar);
     102    Foobar(Foobar & oldFoobar);
     103
     104    int Foo();
     105    double Bar();
     106
     107    SetFoo(int foo);
     108    SetBar(double bar);
     109
     110    bool IsBeyondRecognition();
     111
     112private:
     113
     114    int m_Foo;
     115    double m_Bar;
     116};
     117
     118bool Foobar::IsBeyondRecognition()
     119{
     120    bool is_beyond_recon = false;
     121
     122    if(m_Foo > 100 || m_Bar > 10000.0)
     123    {
     124       is_beyond_recon = true;
     125    }
     126    else
     127    {
     128        int temp_foo = 3;
     129        double temp_bar = m_Bar + 100.0;
     130        while(temp_foo != 10)
     131        {
     132            if(temp_foo > 8 && temp_bar < 300.0)
     133            {
     134                is_beyond_recon = true;
     135                break;
     136            }
     137            else
     138            {
     139                temp_bar = this.GetNewBar(temp_bar);
     140            }
     141           
     142            temp_foo += 1;
     143        }
     144    }
     145
     146    return is_beyond_recon;
     147}
     148}}}           
     149           
     150''':FinishUp:'''         
     151
     152=== Tab locations and size conventions ===
     153
     154''':FinishUp:'''
     155
     156=== Scoping of class attributes ===
     157
     158 (e.g. only private class attributes, public for structures)
     159'''FinishUp:'''
     160
    81161=== NAMES - General Discussion ===
    82162
     
    120200
    121201==== Include Units in Names when Appropriate ====
     202
    122203If a variable represents time, weight, or some other unit then include the unit in the name so developers can more easily spot problems, and also know what values to use as input.
    123204
     
    198279
    199280==== Class Attribute Names ====
     281
    200282  * Attribute names should be prepended with the character 'm_'.
    201283  * After the 'm' use the same rules as for class names.
     
    373455
    374456
    375 ''':Continue Editing From Here: - DCT'''
    376 
    377457==== Enum Names ====
    378 Labels All Upper Case with '_' Word Separators
    379 This is the standard rule for enum labels.
    380 
    381 Example
     458  * Labels should be All Upper Case with '_' Word Separators
     459  * This is the standard rule for enum labels.
     460
     461Example
     462{{{
    382463   enum PinStateType
    383464   {
     
    385466      PIN_ON
    386467   };
     468}}}
    387469
    388470==== Enums as Constants without Class Scoping ====
    389 Sometimes people use enums as constants. When an enum is not embedded in a class, make sure you use some sort of differentiating name before the label so as to prevent name clashes.
    390 Example
    391    enum PinStateType            If PIN was not prepended a conflict
     471
     472  * Sometimes people use enums as constants.
     473  * When an enum is not embedded in a class, make sure you use some sort of differentiating name before the label so as to prevent name clashes.
     474
     475Example
     476{{{
     477   enum PinStateType            If PIN was not prepended, a conflict
    392478   {                            would occur as OFF and ON are probably
    393479      PIN_OFF,                  already defined.
    394480      PIN_ON
    395481   };
     482}}}
    396483
    397484==== Enums with Class Scoping ====
    398485
    399 Just name the enum items what you wish and always qualify with the class name: Aclass::PIN_OFF.
    400 Make a Label for an Error State
    401 It's often useful to be able to say an enum is not in any of its valid states. Make a label for an uninitialized or error state. Make it the first label if possible.
    402 Example
    403 enum { STATE_ERR,  STATE_OPEN, STATE_RUNNING, STATE_DYING};
     486  * Just name the enum items what you wish and always qualify with the class name: Aclass::PIN_OFF.
     487  * Make a Label for an Error State
     488  * It's often useful to be able to say an enum is not in any of its valid states. Make a label for an uninitialized or error state. Make it the first label if possible.
     489
     490Example
     491{{{
     492   enum
     493   {
     494      STATE_ERR, 
     495      STATE_OPEN,
     496      STATE_RUNNING,
     497      STATE_DYING
     498   };
     499}}}
    404500
    405501==== #define and Macro Names ====
    406 •       Put #defines and macros in all upper using '_' separators.
    407 Justification
    408 This makes it very clear that the value is not alterable and in the case of macros, makes it clear that you are using a construct that requires care.
    409 Some subtle errors can occur when macro names and enum labels use the same name.
    410 Example
     502
     503  * Put #defines and macros in all upper using '_' separators.
     504
     505Justification
     506
     507  * This makes it very clear that the value is not alterable and in the case of macros, makes it clear that you are using a construct that requires care.
     508  * Some subtle errors can occur when macro names and enum labels use the same name.
     509
     510Example
     511{{{
    411512#define MAX(a,b) blah
    412513#define IS_ERR(err) blah
    413 
     514}}}
    414515
    415516==== C Function Names ====
    416 •       In a C++ project there should be very few C functions.
    417 •       For C functions use the GNU convention of all lower case letters with '_' as the word delimiter.
    418 Justification
    419 •       It makes C functions very different from any C++ related names.
    420 Example
    421    int
    422    some_bloody_function()
     517  * In a C++ project there should be very few C functions.
     518  * For C functions use the GNU convention of all lower case letters with '_' as the word delimiter.
     519
     520Justification
     521  * It makes C functions very different from any C++ related names.
     522
     523Example
     524{{{
     525   int some_strange_c_function()
    423526   {
    424527   }
    425 
     528}}}
    426529
    427530==== C++ File Extensions ====
     531
    428532In short: Use the .h extension for header files and .cc for source files.
    429533For some reason an odd split occurred in early C++ compilers around what C++ source files should be called. C header files always use the .h and C source files always use the .c extension. What should we use for C++?
     
    432536
    433537Historically speaking here have been the options:
    434 •       Header Files: .h, .hh, .hpp
    435 •       Source Files: .C, .cpp, .cc
     538  * Header Files: .h, .hh, .hpp
     539  * Source Files: .C, .cpp, .cc
    436540
    437541==== Header File Extension Discussion ====
    438 Using .hh extension is not widely popular but makes a certain kind of sense. C header files use .h file extension and C++ based header files use .hh file extension. The problem is if we consider a header file an interface to a service then we can have a C interface to a service and C++ interface to the service in the same file. Using preprocessor directives this is possible and common. The recommendation is to stick with using the .h extension.
     542
     543Using .hh extension is not widely popular but makes a certain kind of sense, i.e. C header files use .h file extension and C++ based header files use .hh file extension. '''The problem is''' if we consider a header file an interface to a service then we can have a C interface to a service and C++ interface to the service in the same file. Using preprocessor directives this is possible and common. The recommendation is to stick with using the .h extension.
    439544 
    440545==== Source File Extension Discussion ====
     546
    441547The problem with the .C extension is that it is indistinguishable from the .c extensions in operating systems that aren't case sensitive. Yes, this is a UNIX vs. windows issue. Since it is a simple step aiding portability we won't use the .C extension. The .cpp extension is a little wordy. So the .cc extension wins by default.
    442548
    443549
    444 
    445 
     550=== Misc ===
     551
     552''' :FinishUp: all of these! '''
     553
     554  * One declaration at a time
     555  * always 'spell out' boolean equality
     556  * use header file protection
     557  * use const as much as possible
     558  * keep scope on variables as low as possible
     559  * if ( isGood == true ) vs. if(isGood==true)
     560