Changes between Version 7 and Version 8 of CppCodingStandards


Ignore:
Timestamp:
Jul 21, 2009, 5:34:04 PM (10 years ago)
Author:
dtodd
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • CppCodingStandards

    v7 v8  
    143143Example:
    144144{{{
    145    class FluidOz             // NOT FluidOZ
    146    class NetworkAbcKey       // NOT NetworkABCKey
    147 }}}
    148 
    149 
    150 ''':Continue Editing Here: - DCT'''
     145   class FluidOz;             // NOT FluidOZ
     146   class NetworkAbcKey;       // NOT NetworkABCKey
     147}}}
    151148
    152149
     
    154151
    155152==== Class Names ====
    156 •       Use upper case letters as word separators, lower case for the rest of a word
    157 •       First character in a name is upper case
    158 •       No underbars ('_')
    159 Justification
    160 •       Of all the different naming strategies many people found this one the best compromise.
    161 Example
    162    class NameOneTwo
    163  
    164    class Name
    165 
     153
     154  * Use upper case letters as word separators, lower case for the rest of a word (CamelCaseForm)
     155  * First character in a name is upper case
     156  * No underbars ('_')
     157
     158Justification
     159  * Of all the different naming strategies many people found this one the best compromise.
     160
     161Example
     162{{{
     163   class NameOneTwo;
     164   class Name;
     165   class CoolAutomobiles;
     166}}}
    166167
    167168==== Class Library Names ====
    168 •       Now that name spaces are becoming more widely implemented, name spaces should be used to prevent class name conflicts among libraries from different vendors and groups.
    169 •       When not using name spaces, it's common to prevent class name clashes by prefixing class names with a unique string. Two characters is sufficient, but a longer length is fine.
    170 Example
    171 John Johnson's complete data structure library could use JJ as a prefix, so classes would be:
    172  
     169
     170  * Name spaces will hopefully make this section unnecessary, but use this if you're working with older code and need to add a new library.
     171  * i.e. ''When not using name spaces'', it's common to prevent class name clashes by prefixing class names with a unique string. Two characters is often sufficient, but a longer length is fine.
     172
     173Example
     174
     175John Johnson's data structure library could use JJ as a prefix, so classes would be:
     176{{{
    173177   class JjLinkList
    174178   {
    175    }
    176 
    177 
    178 === Method Names ===
    179 •       Use the same rule as for class names.
    180 Justification
    181 •       Of all the different naming strategies many people found this one the best compromise.
    182 Example
     179   };
     180}}}
     181
     182=== Class Method Names ===
     183  * Use the same rule as for class names.
     184  * i.e. use camel case, first letter capital, no "_" underbars.
     185
     186Justification
     187  * Of all the different naming strategies, this one is the best compromise.
     188
     189Example
     190{{{
    183191   class NameOneTwo
    184192   {
     
    186194      int                   DoIt();
    187195      void                  HandleError();
    188    }
    189 
     196   };
     197}}}
    190198
    191199==== Class Attribute Names ====
    192 •       Attribute names should be prepended with the character 'm'.
    193 •       After the 'm' use the same rules as for class names.
    194 •       'm' always precedes other name modifiers like 'p' for pointer.
    195 Justification
    196 •       Prepending 'm' prevents any conflict with method names. Often your methods and attribute names will be similar, especially for accessors.
    197 Example
    198    class NameOneTwo
     200  * Attribute names should be prepended with the character 'm_'.
     201  * After the 'm' use the same rules as for class names.
     202  * 'm' always precedes other name modifiers like 'p' for pointer, or 'r' for reference.
     203 
     204Justification
     205
     206  * Prepending 'm_' prevents any conflict with method names. Often your methods and attribute names will be similar, especially for accessors.
     207
     208Example
     209{{{
     210   class TreeHouse
    199211   {
    200212   public:
     
    205217      int                   m_ErrorNumber;
    206218      String*               m_pName;
    207    }
    208 
    209 The original spec had mTimoutMsecs, but I think that m_TimeoutMsecs is more clear as the m is separated from the "TimeoutMsecs".  My only reservation is that it's harder to type, but usually worth the extra effort.
    210 
    211 
    212 ==== Method Argument Names ====
    213 •       The first character should be lower case.
    214 •       All word beginnings after the first letter should be upper case as with class names.
    215 Justification
    216 •       You can always tell which variables are passed in variables.
    217 •       You can use names similar to class names without conflicting with class names.
    218 Example
     219      Deck&                 m_rDeck;
     220   };
     221}}}
     222
     223The original spec had mVarAbc, but I think that m_VarAbc is more clear as the m is separated from the "VarAbc".  My only reservation is that it's harder to type, but usually worth the extra effort.
     224
     225
     226==== Method Argument Variable Names ====
     227  * The first character should be lower case.
     228  * All word beginnings after the first letter should be upper case as with class names.
     229
     230Justification
     231  * You can always tell which variables are passed in variables.
     232  * You can use names similar to class names without conflicting with class names.
     233
     234Example
     235{{{
    219236   class NameOneTwo
    220237   {
    221238   public:
    222       int  StartYourEngines(Engine& rSomeEngine,
    223                             Engine& rAnotherEngine);
    224    }
    225 
     239      int  CompareEngines(Engine& rSomeEngine,
     240                          Engine& rAnotherEngine,
     241                          int comparisonFlag,
     242                          bool doItRight);
     243   };
     244}}}
    226245
    227246==== Variable Names on the Stack ====
     
    229248i.e. Automatic variables.
    230249
    231 •       use all lower case letters
    232 •       use '_' as the word separator.
    233 Justification
    234 •       With this approach the scope of the variable is clear in the code.
    235 •       Now all variables look different and are identifiable in the code.
    236 Example
    237    int
    238    NameOneTwo::HandleError(int errorNumber)
    239    {
    240       int            error= OsErr();
     250  * use all lower case letters
     251  * use '_' as the word separator.
     252
     253Justification
     254  * With this approach the scope of the variable is clear in the code.
     255  * Now all variables look different and are identifiable in the code.
     256
     257Example
     258{{{
     259   int NameOneTwo::HandleError(int errorNumber)
     260   {
     261      int            error = OsErr();
    241262      Time           time_of_error;
    242263      ErrorProcessor error_processor;
    243264      Time*          p_out_of_time= 0;
    244265   }
     266}}}
    245267
    246268The standard pointer notation is not entirely satisfactory because it doesn't look quite right, but it is consistent.
    247269
    248 How do you handle statics? There's never a reason to have a static local to a function so there's no reason to invent a syntax for it. But like for most absolute rules, there is an exception, that is when making singletons. Use a "s_" prefix in this case. Take a look at Singleton Pattern for more details.
     270How to handle statics?
     271
     272There's almost never a reason to have a static local to a function so there's no reason to invent a syntax for it. But like for most rules, there is an exception, that is when making singletons. Use a "s_" prefix in this case. Take a look at Singleton Pattern for more details.
    249273
    250274
    251275==== Pointer Variables ====
    252 •       pointers should be prepended by a 'p' in most cases
    253 •       place the * close to the pointer type not the variable name
    254 
    255 Justification
    256 •       The idea is that the difference between a pointer, object, and a reference to an object is important for understanding the code, especially in C++ where -> can be overloaded, and casting and copy semantics are important.
    257 
    258 •       Pointers really are a change of type so the * belongs near the type. One reservation with this policy relates to declaring multiple variables with the same type on the same line. In C++ the pointer modifier only applies to the closest variable, not all of them, which can be very confusing, especially for newbies. You want to have one declaration per line anyway so you can document each variable.
    259 
    260 Example
    261   String* pName= new String;
    262 
    263   String* pName, name, address; // note, only pName is a pointer.
    264 
     276  * pointers should be prepended by a 'p' or a 'p_' in most cases (when are the :Exeptions:?).
     277  * place the * close to the pointer type not the variable name
     278
     279Justification
     280
     281  * The idea is that the difference between a pointer, object, and a reference to an object is important for understanding the code, especially in C++ where -> can be overloaded, and casting and copy semantics are important.
     282
     283  * Pointers really imply a modification of type, so the * belongs near the type. One reservation with this policy relates to declaring multiple variables with the same type on the same line. In C++ the pointer modifier only applies to the closest variable, not all of them, which can be very confusing, especially for newbies.
     284
     285  * '''For this reason, and for documentation reasons, only have one declaration per line.'''
     286
     287Example
     288{{{
     289  String* pName = new String;
     290
     291  String* pName, name, address; // note, only pName is a pointer.  __DON'T DO THIS__
     292}}}
    265293
    266294==== Reference Variables and Functions Returning References ====
    267 •       References should be prepended with 'r'.
    268 Justification
    269 •       The difference between variable types is clarified.
    270 •       It establishes the difference between a method returning a modifiable object and the same method name returning a non-modifiable object.
    271 Example
     295  * References should be prepended with 'r'.
     296
     297Justification
     298  * The difference between variable types is clarified.
     299  * It establishes the difference between a method returning a modifiable object and the same method name returning a non-modifiable object.
     300
     301Example
     302{{{
    272303   class Test
    273304   {
     
    279310
    280311   private:
    281       StatusInfo&        mrStatus;
    282    }
    283 
     312      StatusInfo&        m_rStatus;
     313
     314   };
     315}}}
    284316
    285317==== Global Variables ====
    286 •       Global variables should be prepended with a 'g'.
    287 Justification
    288 •       It's important to know the scope of a variable.
    289 Example
    290     Logger  gLog;
    291     Logger* gpLog;
    292 
     318  * Global variables should be prepended with a 'g_'. Originally this had just a 'g', but since we are using 'm_' for class attributes, I think using 'g_' for global would distinguish the scope form the type ('p' and 'r').
     319
     320Justification
     321  * It's important to know the scope of a variable.
     322
     323Example
     324{{{
     325    Logger  g_Log;
     326    Logger* g_pLog;
     327}}}
    293328
    294329==== Global Constants ====
    295 •       Global constants should be all caps with '_' separators.
    296 Justification
    297 It's tradition for global constants to named this way. You must be careful to not conflict with other global #defines and enum labels.
    298 Example
    299     const int A_GLOBAL_CONSTANT= 5;
    300 
     330  * Global constants should be all caps with '_' separators.
     331
     332Justification
     333  * It's tradition for global constants to named this way. You must be careful to not conflict with other global #defines and enum labels.
     334
     335Example
     336{{{
     337    const int GLOBAL_CONSTANT_FIVE = 5;
     338}}}
    301339
    302340==== Static Variables ====
    303 •       Static variables may be prepended with 's'.
    304 Justification
    305 •       It's important to know the scope of a variable.
    306 Example
     341  * Static variables should be prepended with 's_'.
     342
     343Justification
     344  * It's important to know the scope of a variable.
     345  * while this may seem a bit cumbersome, static variables should not be used that often.
     346  * Alternative choices are sm_Status, ms_Status, and m_sStatus and msStatus.  None of which is satisfactory.
     347
     348Example
     349{{{
    307350   class Test
    308351   {
    309352   public:
    310353   private:
    311       static StatusInfo msStatus;
    312    }
    313 
     354      static StatusInfo m_s_Status;
     355   };
     356}}}
    314357
    315358==== Type Names ====
    316 •       When possible for types based on native types make a typedef.
    317 •       Typedef names should use the same naming policy as for a class with the word Type appended.
    318 Justification
    319 •       Of all the different naming strategies many people found this one the best compromise.
    320 •       Types are things so should use upper case letters. Type is appended to make it clear this is not a class.
    321 Example
     359  * When possible for types based on native types make a typedef.
     360  * Typedef names should use the same naming policy as for a class with the word Type appended.
     361
     362Justification
     363  * Of all the different naming strategies many people found this one the best compromise.
     364  * Types are things so should use upper case letters. Type is appended to make it clear this is not a class.
     365
     366Example
     367{{{
    322368   typedef uint16  ModuleType;
    323369   typedef uint32  SystemType;
    324 
     370}}}
     371
     372'''One should be careful about when and why to create a type from system types, as it creates confusion for readers.  What is a SystemType?  Why not just call things of that type uint32?  If there is no good reason then don't do it!'''
     373
     374
     375''':Continue Editing From Here: - DCT'''
    325376
    326377==== Enum Names ====
    327378Labels All Upper Case with '_' Word Separators
    328379This is the standard rule for enum labels.
     380
    329381Example
    330382   enum PinStateType