C++ Programming Style Guidelines

8/3/2019 C++ Programming Style Guidelines

1/20

P a g e 1 C + + P r o g r a m m i n g S t y l e G u i d e l i n e s

d i 0 1 m e i 2 0 0 7 0 8 : 2 2 : 4 7 C E S T h t t p : / / g e o s o f t . n o / d e v e l o p m e n t / c p p s t y l e . h t m l

C++ Programming Style Guidelines

Version 4.5, April 2007Geotechnical Software Services

Copyright 1996 - 2007

This document is available at http://geosoft.no/development/cppstyle.html

Table of Content

1 Introduction1.1 Layout of the Recommendations1.2 Recommendations Importance

2 General Recommendations3 Naming Conventions

3.1 General3.2 Specific

4 Files4.1 Source Files4.2 Include Files and Include Statements

5 Statements5.1 Types5.2 Variables5.3 Loops5.4 Conditionals5.5 Miscellaneous

6 Layout and Comments6.1 Layout6.2 White space6.3 Comments

7 References

1 Introduction

This document lists C++ coding recommendations common in the C++ development community.

The recommendations are based on established standards collected from a number of sources, individ ualexperience, local requirements/needs, as well as suggestions given in [1] - [4].

There are several reasons for introducing a new guideline rather than just referring to the ones above. Mainreason is that these guides are far too general in their scope and that more specific rules (especially namingrules) need to be established. Also, the present guide has an annotated form that makes it far easier to useduring project code reviews than most other existing guidelines. In addition, programming recommendationsgenerally tend to mix style issues with language technical issues in a somewhat confusing manner. Thepresent document does not contain any C++ technical recommendations at all, but focuses mainly onprogramming style. For guidelines on C++ programming stylerefer to the C++ Programming PracticeGuidelines.

While a given development envi ronment (IDE) can improve the readability of code by access visibility, colorcoding, automatic formatting and so on, the programmer should never relyon such features. Source codeshould always be considered largerthan the IDE it is developed within and should be written in a way thatmaximize its readability independent of any IDE.

1.1 Layout of the Recommendations.

The recommendations are grouped by topic and each recommendation is numbered to make it easier torefer to during reviews.

Layout of the recommendations is as follows:

n. Guideline short description


2/20



E x a m p l e i f a p p l i c a b l e

Motivation, background and additional information.

The motivation section is important. Coding standards and guidel ines tend to start "religious wars", and it isimportant to state the background for the recommendation.

1.2 Recommendation Importance

In the guideline sections the terms must, shouldand can have special meaning. A mustrequirement must befollowed, a shouldis a strong recommendation, and a can is a general guideline.

2 General Recommendations

1. Any violation to the guide is allowed if it enhances readability.

The main goal of the recommendation is to improve readability and thereby the understanding and themaintainability and general quality of the code. It is impossible to cover all the specific cases in a generalguide and the programmer should be flexible.

2. The rules can be violated if there are strong personal objections against them.

The attempt is to make a guideline, not to force a particular coding style onto individuals. Experiencedprogrammers normally want adopt a style like this anyway, but having one, and at least requiring everyoneto get familiar with it, usually makes people start thinkingabout programming style and evaluate their ownhabits in this area.

On the other hand, new and inexperienced programmers normally use a style guide as a convenience ofgetting into the programming jargon more easily.

3 Naming Conventions3.1 General Naming Conventions

3. Names representing types must be in mixed case starting with upper case.

L i n e , S a v i n g s A c c o u n t

Common practice in the C++ development community.

4. Variable names must be in mixed case starting with lower case.

l i n e , s a v i n g s A c c o u n t

Common practice in the C++ development community. Makes variables easy to distinguish from types,and effectively resolves potential naming collision as in the declaration Line line;


3/20



5. Named constants (including enumeration values) must be all uppercase using underscore toseparate words.

M A X _ I T E R A T I O N S , C O L O R _ R E D , P I

Common practice in the C++ development community. In general, the use of such constants should beminimized. In many cases implementing the value as a method is a better choice:

i n t g e t M a x I t e r a t i o n s ( ) / / N O T : M A X _ I T E R A T I O N S = 2 5

{

r e t u r n 2 5 ;

}

This form is both easier to read, and it ensures a unified interface towards class values.

6. Names representing methods or functions must be verbs and written in mixed case starting withlower case .

g e t N a m e ( ) , c o m p u t e T o t a l W i d t h ( )

Common practice in the C++ development community. This is identical to variable names, but functions inC++ are already distingushable from variables by their specific form.

7. Names representing namespaces should be all lowercase.

m o d e l : : a n a l y z e r , i o : : i o m a n a g e r , c o m m o n : : m a t h : : g e o m e t r y

Common practice in the C++ development community.

8. Names representing template types should be a single uppercase letter.

t e m p l a t e < c l a s s T > . . .

t e m p l a t e < c l a s s C , c l a s s D > . . .

Common practice in the C++ development community. This makes template names stand out relative to allother names used.

9. Abbreviations and acronyms must not be uppercase when used as name [4].

e x p o r t H t m l S o u r c e ( ) ; / / N O T : e x p o r t H T M L S o u r c e ( ) ;

o p e n D v d P l a y e r ( ) ; / / N O T : o p e n D V D P l a y e r ( ) ;

Using all uppercase for the base name will give conflicts with the naming conventions given above. Avariable of this type whould have to be named dVD, hTML etc. which obviously is not very readable.

Another problem is illustrated in the examples above; When the name is connected to another, thereadbility is seriously reduced; the word following the abbreviation does not stand out as it should.

10. Global variables should always be referred to using the :: operator.

: : m a i n W i n d o w . o p e n ( ) , : : a p p l i c a t i o n C o n t e x t . g e t N a m e ( )

In general, the use of global variables should be avoided. Consider using singleton objects instead.

11. Private class variables should have underscore suffix.

c l a s s S o m e C l a s s {

p r i v a t e :

i n t l e n g t h _ ;

}


4/20



Apart from its name and its type, the scopeof a variable is its most important feature. Indicating classscope by using underscore makes it easy to distinguish class variables from local scratch variables. This isimportant because class variables are considered to have higher significance than method variables, andshould be treated with special care by the programmer.

A side effect of the underscore naming convention is that it nicely resolves the problem of findingreasonable variable names for setter methods and constructors:

v o i d s e t D e p t h ( i n t d e p t h )

{

d e p t h _ = d e p t h ;

}

An issue is whether the underscore should be ad ded as a prefix or as a suffix. Both practices arecommonly used, but the latter is recommended because it seem to best preserve the readability of thename.

It should be note d that scope identification in variables has been a controversial issue for quite some time.It seems, though, that this practice now is gaining acceptance and that it is becoming more and more

common as a convention in the professional development community.

12. Generic variables should have the same name as their type.

v o i d s e t T o p i c ( T o p i c * t o p i c ) / / N O T : v o i d s e t T o p i c ( T o p i c *

v a l u e )

/ / N O T : v o i d s e t T o p i c ( T o p i c *

a T o p i c )

/ / N O T : v o i d s e t T o p i c ( T o p i c *

t )

v o i d c o n n e c t ( D a t a b a s e * d a t a b a s e ) / / N O T : v o i d c o n n e c t

( D a t a b a s e * d b )

/ / N O T : v o i d c o n n e c t

( D a t a b a s e * o r a c l e D B )

Reduce complexity by reducing the number of terms and names used. Also makes it easy to deduce thetype given a variable name only.

If for some reason this convention doesn't seem to fitit is a strong indication that the type name is badlychosen.

Non-generic variables have a role. These variables can often be named by combining role and type:

P o i n t s t a r t i n g P o i n t , c e n t e r P o i n t ;

N a m e l o g i n N a m e ;

13. All names should be written in English.

f i l e N a m e ; / / N O T : f i l N a v n

English is the prefered language for international development.

14. Variables with a large scope should have long names, variables with a small scope can haveshort names [1].

Scratch variables used for temporary storage or indices are best kept short. A programmer reading suchvariables should be able to assume that its value is not used outside a few lines of code. Common scratchvariables for integers are i,j, k, m, nand for characters cand d.


5/20



15. The name of the object is implicit, and should be avoided in a method name.

l i n e . g e t L e n g t h ( ) ; / / N O T : l i n e . g e t L i n e L e n g t h ( ) ;

The latter seems natural in the class declaration, but proves superfluous in use, as shown in the example.

3.2 Specific Naming Conventions

17. The terms get/setmust be used where an attribute is accessed directly.

e m p l o y e e . g e t N a m e ( ) ;

e m p l o y e e . s e t N a m e ( n a m e ) ;

m a t r i x . g e t E l e m e n t ( 2 , 4 ) ;

m a t r i x . s e t E l e m e n t ( 2 , 4 , v a l u e ) ;

Common practice in the C++ development community. In Java this convention has become more or less

standard.

18. The term computecan be used in methods where something is computed.

v a l u e S e t > c o m p u t e A v e r a g e ( ) ;

m a t r i x > c o m p u t e I n v e r s e ( )

Give the reader the immediate clue that this is a potential time consuming operation, and if usedrepeatedly, he might consider caching the result. Consistent use of the term enhances readability.

19. The term findcan be used in methods where something is looked up.

v e r t e x . f i n d N e a r e s t V e r t e x ( ) ;

m a t r i x . f i n d M i n E l e m e n t ( ) ;

Give the reader the immediate clue that this is a simple look up method with a minimum of computationsinvolved. Consistent use of the term enhances readability.

20. The term initializecan be used where an object or a concept is established.

p r i n t e r . i n i t i a l i z e F o n t S e t ( ) ;

The american initialize should be preferred over the English initialise. Abbreviation initshould be avoided.

21. Variables representing GUI components should be suffixed by the component type name.

m a i n W i n d o w , p r o p e r t i e s D i a l o g , w i d t h S c a l e , l o g i n T e x t ,

l e f t S c r o l l b a r , m a i n F o r m , f i l e M e n u , m i n L a b e l , e x i t B u t t o n ,

y e s T o g g l e e t c .

Enhances readability since the name gives the user an immediate clue of the type of the variable andthereby the objects resources.


6/20



22. Plural form should be used on names representing a collection of objects.

v e c t o r < P o i n t > p o i n t s ;

i n t v a l u e s [ ] ;

Enhances readability since the name gives the user an immediate clue of the type of the variable and theoperations that can be performed on its elements.

23. The prefix nshould be used for variables representing a number of objects.

n P o i n t s , n L i n e s

The notation is taken from mathematics where it is an established convention for indicating a number ofobjects.

24.The suffix Noshould be used for variables representing an entity number.

t a b l e N o , e m p l o y e e N o

The notation is taken from mathematics where it is an established convention for indicating an entitynumber.

An elegant alternative is to prefix such variables with an i:i T a b l e , i E m p l o y e e

. This effectively makesthem named iterators.

25. Iterator variables should be called i,j, ketc.

f o r ( i n t i = 0 ; i < n T a b l e s ) ; i + + ) {

:

}

f o r ( v e c t o r < M y C l a s s > : : i t e r a t o r i = l i s t . b e g i n ( ) ; i ! =

l i s t . e n d ( ) ; i + + ) {

E l e m e n t e l e m e n t = * i ;

. . .

}

The notation is taken from mathematics where it is an established convention for indicating iterators.

Variables named j, ketc. should be used for nested loops only.

26. The prefix isshould be used for boolean variables and methods.

i s S e t , i s V i s i b l e , i s F i n i s h e d , i s F o u n d , i s O p e n

Common practice in the C++ development community and partially enforced in Java.

Using the isprefix solves a common problem of choosing bad boolean names like s t a t u s or f l a g .

i s S t a t u s or i s F l a g simply doesn't fit, and the programmer is forced to choose more meaningful names.

There are a few alternatives to the isprefix that fits better in some situations. These are the has, can andshouldprefixes:

b o o l h a s L i c e n s e ( ) ;

b o o l c a n E v a l u a t e ( ) ;

b o o l s h o u l d S o r t ( ) ;

27. Complement names must be used for complement operations [1].


7/20



g e t / s e t , a d d / r e m o v e , c r e a t e / d e s t r o y , s t a r t / s t o p , i n s e r t /

d e l e t e ,

i n c r e m e n t / d e c r e m e n t , o l d / n e w , b e g i n / e n d , f i r s t / l a s t , u p /

d o w n , m i n / m a x ,

n e x t / p r e v i o u s , o l d / n e w , o p e n / c l o s e , s h o w / h i d e , s u s p e n d /

r e s u m e , e t c .

Reduce complexity by symmetry.

28. Abbreviations in names should be avoided.

c o m p u t e A v e r a g e ( ) ; / / N O T : c o m p A v g ( ) ;

There are two types of words to consider. First are the common words listed in a languag e dictionary.These must never be abbreviated. Never write:

c m d

instead ofc o m m a n d

c p instead of c o p y

p t instead of p o i n t

c o m p instead of c o m p u t e

i n i t instead of i n i t i a l i z e etc.

Then there are domain specific phrases that are more naturally known through their abbreviations/acronym. These phrases should be kept abbreviated. Never write:

H y p e r t e x t M a r k u p L a n g u a g e instead of h t m l

C e n t r a l P r o c e s s i n g U n i t instead of

c p u

P r i c e E a r n i n g R a t i o instead of p eetc.

29. Naming pointers specifically should be avoided.

L i n e * l i n e ; / / N O T : L i n e * p L i n e ;

/ / N O T : L I n e * l i n e P t r ;

Many variables in a C/C++ environment are pointers, so a convention like this is almost impossible tofollow. Also objects in C++ are often oblique types where the specific implementation should be ignoredby the programmer. Only when the actual type of an object is of special significance, the name shouldempahsize the type.

30. Negated boolean variable names must be avoided.

b o o l i s E r r o r ; / / N O T : i s N o E r r o r

b o o l i s F o u n d ; / / N O T : i s N o t F o u n d

The problem arises when such a name is used in conjunction with the logical negation operator as this

results in a double negative. It is not immediately apparent what ! i s N o t F o u n d means.

31. Enumeration constants can be prefixed by a common type name.

e n u m C o l o r {

C O L O R _ R E D ,

C O L O R _ G R E E N ,

C O L O R _ B L U E

} ;


8/20



This gives additional information of where the declaration can be found, which constants belongs together,and what concept the constants represent.

An alternative approach is to always refer to the constants through their common type: C o l o r : : R E D ,

A i r l i n e : : A I R _ F R A N C E

etc.

32. Exception classes should be suffixed with Exception.

c l a s s A c c e s s E x c e p t i o n

{

:

}

Exception classes are really not part of the main design of the program, and naming them like this makesthem stand out relative to the other classes.

33. Functions (methods returning something) should be named after what they return and procedures(voidmethods) after what they do.

Increase readability. Makes it clear what the unit should do and especially all the things it is not supposedto do. This again makes it easier to keep the code clean of side effects.

4 Files

4.1 Source Files

34. C++ header files should have the extension .h. Source files can have the extension .c++(recommended), .C, .ccor .cpp.

M y C l a s s . c + + , M y C l a s s . h

These are all accepted C++ standards for file extension.

35. A class should be declared in a header file and defined in a source file where the name of the filesmatch the name of the class.

M y C l a s s . h , M y C l a s s . c + +

Makes it easy to find the associated files of a given class. An obvious exception is template classes thatmust be both declared and defined inside a .h file.

36. All definitions should reside in source files.

c l a s s M y C l a s s

{

p u b l i c :

i n t g e t V a l u e ( ) { r e t u r n v a l u e _ ; } / / N O !

. . .

p r i v a t e :

i n t v a l u e _ ;

}

The header files should declare an interface, the source file should implement it. When looking for an

implementation, the programmer should always know that it is found in the source file. The obviousexception to this rule is of course inline functions that must be defined in the header file.


9/20



37. File content must be kept within 80 columns.

80 columns is a common dimension for editors, terminal emulators, printers and debuggers, and files thatare shared between several people should keep within these constraints. It improves readability whenunintentional line breaks are avoided when passing a file between programmers.

38. Special characters like TAB and page break must be avoided.

These characters are bound to cause problem for editors, printers, terminal emulators or debuggers whenused in a multi-programmer, multi-platform environment.

39. The incompleteness of split lines must be made obvious [1].

t o t a l S u m = a + b + c +

d + e ;

f u n c t i o n ( p a r a m 1 , p a r a m 2 ,

p a r a m 3 ) ;

s e t T e x t ( " L o n g l i n e s p l i t "

" i n t o t w o p a r t s . " ) ;

f o r ( i n t t a b l e N o = 0 ; t a b l e N o < n T a b l e s ;

t a b l e N o + = t a b l e S t e p ) {

. . .

}

Split lines occurs when a statement exceed the 80 column limit given above. It is difficult to give rigid rulesfor how lines should be split, but the examples above should give a general hint.

In general:

Break after a comma.Break after an operator.Align the new line with the beginning of the expression on the previous line.

4.2 Include Files and Include Statements

40. Header files must contain an include guard.

# i f n d e f C O M _ C O M P A N Y _ M O D U L E _ C L A S S N A M E _ H

# d e f i n e C O M _ C O M P A N Y _ M O D U L E _ C L A S S N A M E _ H

:

# e n d i f

The construction is to avoid compilation errors. The name convention resembles the location of the fileinside the source tree and prevents naming conflicts.

41. Include statements should be sorted and grouped. Sorted by their hierarchical position in thesystem with low level files included first. Leave an empty line between groups of include statements.


10/20

P a g e 1 0 C + + P r o g r a m m i n g S t y l e G u i d e l i n e s


# i n c l u d e < f s t r e a m >

# i n c l u d e < i o m a n i p >

# i n c l u d e < q t / q b u t t o n . h >

# i n c l u d e < q t / q t e x t f i e l d . h >

# i n c l u d e " c o m / c o m p a n y / u i / P r o p e r t i e s D i a l o g . h "

# i n c l u d e " c o m / c o m p a n y / u i / M a i n W i n d o w . h "

In addition to show the reader the individual include files, it also give an immediate clue about themodules that are involved.

Include file paths must never be absolute. Compiler directives should instead be used to indicate rootdirectories for includes.

42. Include statements must be located at the top of a file only.

Common practice. Avoid unwanted compilation si de effects by "hidden" include statements deep into asource file.

5 Statements

5.1 Types

43. Types that are local to one file only can be declared inside that file.

Enforces information hiding.

44. The parts of a class must be sorted public, protectedand private [2][3]. All sections must beidentified explicitly. Not applicable sections should be left out.

The ordering is "most public first"so people who only wish to use the class can stop reading when theyreach the protected/private sections.

45. Type conversions must always be done explicitly. Never rely on implicit type conversion.

f l o a t V a l u e = s t a t i c _ c a s t < f l o a t > ( i n t V a l u e ) ; / / N O T :

f l o a t V a l u e = i n t V a l u e ;

By this, the programmer indicates that he is aware of the different types involved a nd that the mix is

intentional.

5.2 Variables

46. Variables should be initialized where they are declared.

This ensures that variables are valid at any time. Sometimes it is impossible to initialize a variable to avalid value where it is declared:

i n t x , y , z ;

g e t C e n t e r ( & x , & y , & z ) ;

In these cases it should be left uninitialized rather than initialized to some phony value.

47. Variables must never have dual meaning.


11/20



Enhance readability by ensuring all concepts are represented uniquely. Reduce chance of error by sideeffects.

48. Use of global variables should be minimized.

In C++ there is no reason global variables need to be used at all. The same is true for global functions orfile scope (static) variables.

49. Class variables should never be declared public.

The concept of C++ information hiding and encapsul ation is violated by public variables. Use privatevariables and access functions instead. One exception to this rule is when the class is essentially a datastructure, with no behavior (equivalent to a C struct). In this case it is appropriate to make the class'instance variables public [2].

Note that structs are kept in C++ for compatibility with C only, and avoid ing them increases the readability

of the code by reducing the number of constructs used. Use a class instead.

51. C++ pointers and references should have their reference symbol next to the type rather than tothe name.

f l o a t * x ; / / N O T : f l o a t * x ;

i n t & y ; / / N O T : i n t & y ;

The pointer-nessor reference-nessof a variable is a property of the type rather than the name. C-programmers often use the alternative approach, while in C++ it has become more common to follow thisrecommendation.

53. Implicit test for 0should not be used other than for boolean variables and pointers.

i f ( n L i n e s ! = 0 ) / / N O T : i f ( n L i n e s )

i f ( v a l u e ! = 0 . 0 ) / / N O T : i f ( v a l u e )

It is not necessarily defined by the C++ standard that ints and floats 0 are implemented as binary 0. Also,by using explicit test the statement give immediate clue of the type being tested.

It is common also to suggest that pointers shouldn't test implicit for 0 either, i.e. i f ( l i n e = = 0 ) instead

ofi f ( l i n e )

. The latter is regarded so common in C/C++ however that it can be used.

54. Variables should be declared in the smallest scope possible.

Keeping the operations on a variable within a small scope, it is easier to control the effects and side effectsof the variable.

5.3 Loops

55. Only loop control statements must be included in the f o r ( ) construction.

s u m = 0 ; / / N O T : f o r ( i = 0 , s u m =

0 ; i < 1 0 0 ; i + + )

f o r ( i = 0 ; i < 1 0 0 ; i + + ) s u m + = v a l u e [ i ] ;

s u m + = v a l u e [ i ] ;

Increase maintainability and readability. Make a clear distinction of what controlsand what is contained in

the loop.


12/20



56. Loop variables should be initialized immediately before the loop.

i s D o n e = f a l s e ; / / N O T : b o o l i s D o n e = f a l s e ;

w h i l e ( ! i s D o n e ) { / / :

: / / w h i l e ( ! i s D o n e ) {

} / / :

/ / }

57. d o w h i l e loops can be avoided.

do-whileloops are less readable than ordinary whileloops and forloops since the conditional is at thebottom of the loop. The reader must scan the entire loop in order to understand the scope of the loop.

In addition, do-whileloops are not needed. Any do-whileloop can easily be rewritten into a whileloop or a

forloop. Reducing the number of constructs used enhance readbility.

58. The use of b r e a k and c o n t i n u e in loops should be avoided.

These statements should only be used if they prove to give higher readability than their structuredcounterparts.

60. The form w h i l e ( t r u e ) should be used for infinite loops.

w h i l e ( t r u e ) {

:

}

f o r ( ; ; ) { / / N O !

:

}

w h i l e ( 1 ) { / / N O !

:

}

Testing against 1 is neither necessary nor meaningful. The form f o r ( ; ; ) is not very readable, and it isnot apparent that this actually is an infinite loop.

5.4 Conditionals

61. Complex conditional expressions must be avoided. Introduce temporary boolean variablesinstead [1].

b o o l i s F i n i s h e d = ( e l e m e n t N o < 0 ) | | ( e l e m e n t N o >

m a x E l e m e n t ) ;

b o o l i s R e p e a t e d E n t r y = e l e m e n t N o = = l a s t E l e m e n t ;

i f ( i s F i n i s h e d | | i s R e p e a t e d E n t r y ) {

:

}

/ / N O T :


13/20



i f ( ( e l e m e n t N o < 0 ) | | ( e l e m e n t N o > m a x E l e m e n t ) | |

e l e m e n t N o = = l a s t E l e m e n t ) {

:

}

By assigning boolean variables to expressions, the program gets automatic documentation. Theconstruction will be easier to read, debug and maintain.

62. The nominal case should be put in the if-part and the exception in the else-part of an if statement[1].

b o o l i s O k = r e a d F i l e ( f i l e N a m e ) ;

i f ( i s O k ) {

:

}

e l s e {

:

}

Makes sure that the exceptions don't obscure the normal path of execution. This is important for both thereadability and performance.

63. The conditional should be put on a separate line.

i f ( i s D o n e ) / / N O T : i f ( i s D o n e ) d o C l e a n u p ( ) ;

d o C l e a n u p ( ) ;

This is for debugging purposes. When writing on a single line, it is not apparent whether the test is reallytrue or not.

64. Executable statements in conditionals must be avoided.

F i l e * f i l e H a n d l e = o p e n ( f i l e N a m e , " w " ) ;

i f ( ! f i l e H a n d l e ) {

:

}

/ / N O T :

i f ( ! ( f i l e H a n d l e = o p e n ( f i l e N a m e , " w " ) ) ) {

:

}

Conditionals with executable statements are just very difficult to read. This is especially true forprogrammers new to C/C++.

5.5 Miscellaneous

65. The use of magic numbers in the code should be avoided. Numbers other than 0and 1 should beconsidered declared as named constants instead.


14/20



If the number does not have an obvious meaning by itself, the readability is enhanced by introducing anamed constant instead. A different approach is to introduce a method from which the constant can beaccessed.

66. Floating point constants should always be written with decimal point and at least one decimal.

d o u b l e t o t a l = 0 . 0 ; / / N O T : d o u b l e t o t a l = 0 ;

d o u b l e s p e e d = 3 . 0 e 8 ; / / N O T : d o u b l e s p e e d = 3 e 8 ;

d o u b l e s u m ;

:

s u m = ( a + b ) * 1 0 . 0 ;

This emphasize the different nature of integer and floating point numbers. Mathematically the two model

completely different and non-compatible concepts.

Also, as in the last example above, it emphasize the type of the assigned variable (s u m

) at a point in thecode where this might not be evident.

67. Floating point constants should always be written with a digit before the decimal point.

d o u b l e t o t a l = 0 . 5 ; / / N O T : d o u b l e t o t a l = . 5 ;

The number and expression system in C++ is borrowed from mathematics and one should adhere tomathematical conventions for syntax wherever possible. Also, 0.5 is a lot more readable than .5; There isno way it can be mixed with the integer 5.

68. Functions must always have the return value explicitly listed.

i n t g e t V a l u e ( ) / / N O T : g e t V a l u e ( )

{

:

}

If not exlicitly listed, C++ implies i n t return value for functions. A programmer must never rely on thisfeature, since this might be confusing for programmers not aware of this artifact.

69. g o t o should not be used.

Goto statements violates the idea of structured code. Only in some very few cases (for instance breakingout of deeply nested structures) should goto be considered, and only if the alternative structuredcounterpart is proven to be less readable.

70. "0" should be used instead of "NULL".

N U L L is part of the standard C library, but is made obsolete in C++.

6 Layout and Comments

6.1 Layout


15/20



71. Basic indentation should be 2.

f o r ( i = 0 ; i < n E l e m e n t s ; i + + )

a [ i ] = 0 ;

Indentation of 1 is to small to emphasize the logical layout of the code. Indentation larger than 4 makesdeeply nested code difficult to read and increase the chance that the lines must be split. Choosingbetween indentation of 2, 3 and 4, 2 and 4 are the more common, and 2 chosen to reduce the chance ofsplitting code lines.

72. Block layout should be as illustrated in example 1 below (recommended) or example 2, and mustnot be as shown in example 3 [4]. Function and class blocks must use the block layout of example 2.

w h i l e ( ! d o n e ) {

d o S o m e t h i n g ( ) ;

d o n e = m o r e T o D o

( ) ;

}

w h i l e ( ! d o n e )

{


d o n e = m o r e T o D o

( ) ;

}

w h i l e ( ! d o n e )

{


d o n e =

m o r e T o D o ( ) ;

}

Example 3 introduce an extra indentation level which does n't emphasize the logical structure of the codeas clearly as example 1 and 2.

73. The c l a s s declarations should have the following form:

c l a s s S o m e C l a s s : p u b l i c B a s e C l a s s

{

p u b l i c :

. . .

p r o t e c t e d :

. . .

p r i v a t e :

. . .

}

This follows partly from the general block rule above.

74. Method definitions should have the following form:

v o i d s o m e M e t h o d ( )

{

. . .

}

This follows from the general block rule above.

75. The i f e l s e class of statements should have the following form:

i f ( c o n d i t i o n ) {

s t a t e m e n t s ;

}


16/20





}

e l s e {


}



}

e l s e i f ( c o n d i t i o n ) {


}

e l s e {


}

This follows partly from the general block rule above. However, it might be discussed if an e l s e clause

should be on the same line as the closing bracket of the previousi f

ore l s e

clause:



} e l s e {


}

The chosen approach is considered better in the way that each part of the i f e l s e statement is written onseparate lines of the file. This should make it easier to manipulate the statement, for instance when moving

e l s e clauses around.

76. A f o r statement should have the following form:

f o r ( i n i t i a l i z a t i o n ; c o n d i t i o n ; u p d a t e ) {


}


77. An empty f o r statement should have the following form:

f o r ( i n i t i a l i z a t i o n ; c o n d i t i o n ; u p d a t e )

;

This emphasize the fact that the for statement is empty and it makes it obvious for the reader that this isintentional. Empty loops should be avoided however.

78. A w h i l e statement should have the following form:

w h i l e ( c o n d i t i o n ) {


}


79. A d o w h i l e statement should have the following form:


17/20



d o {


} w h i l e ( c o n d i t i o n ) ;


80. A s w i t c h statement should have the following form:

s w i t c h ( c o n d i t i o n ) {

c a s e A B C :


/ / F a l l t h r o u g h

c a s e D E F :


b r e a k ;

c a s e X Y Z :


b r e a k ;

d e f a u l t :


b r e a k ;

}

Note that each c a s e keyword is indented relative to the switch statement as a whole. This makes the entireswitch statement stand out. Note also the extra space before the :character. The explicit Fallthrough

comment should be included whenever there is a case statement without a b r e a k statement. Leaving the

b r e a k out is a common error, and it must be made clear that it is intentional when it is not there.

81. A t r y c a t c h statement should have the following form:

t r y {


}

c a t c h ( E x c e p t i o n & e x c e p t i o n ) {


}

This follows partly from the general block rule above. The discussion about closing brackets for i f e l s e

statements apply to thet r y c a t c h

statments.

82. Single statement i f e l s e , f o r or w h i l e statements can be written without brackets.

i f ( c o n d i t i o n )

s t a t e m e n t ;

w h i l e ( c o n d i t i o n )

s t a t e m e n t ;

f o r ( i n i t i a l i z a t i o n ; c o n d i t i o n ; u p d a t e )

s t a t e m e n t ;


18/20


19/20



m a t r i x . s e t E l e m e n t ( 2 , 2 , c o s A n g l e ) ;

m u l t i p l y ( m a t r i x ) ;

Enhance readability by introducing white space between logical units of a block.

87. Methods should be separated by three blank lines.

By making the space larger than space within a method, the methods will stand out within the class.

88. Variables in declarations can be left aligned.

A s c i i F i l e * f i l e ;

i n t n P o i n t s ;

f l o a t x , y ;

Enhance readability. The variables are easier to spot from the types by alignment.

89. Use alignment wherever it enhanbces readability.

i f ( a = = l o w V a l u e ) c o m p u e S o m e t h i n g ( ) ;

e l s e i f ( a = = m e d i u m V a l u e ) c o m p u t e S o m e t h i n g E l s e ( ) ;

e l s e i f ( a = = h i g h V a l u e ) c o m p u t e S o m e t h i n g E l s e Y e t ( ) ;

v a l u e = ( p o t e n t i a l * o i l D e n s i t y ) / c o n s t a n t 1 +

( d e p t h * w a t e r D e n s i t y ) / c o n s t a n t 2 +

( z C o o r d i n a t e V a l u e * g a s D e n s i t y ) / c o n s t a n t 3 ;

m i n P o s i t i o n = c o m p u t e D i s t a n c e ( m i n , x , y , z ) ;

a v e r a g e P o s i t i o n = c o m p u t e D i s t a n c e ( a v e r a g e , x , y , z ) ;

s w i t c h ( v a l u e ) {

c a s e P H A S E _ O I L : s t r c p y ( p h a s e , " O i l " ) ; b r e a k ;

c a s e P H A S E _ W A T E R : s t r c p y ( p h a s e , " W a t e r " ) ; b r e a k ;

c a s e P H A S E _ G A S : s t r c p y ( p h a s e , " G a s " ) ; b r e a k ;

}

There are a number of places in the code where white space can be included to enhance readability even

if this violates common guidelines. Many of these cases have to do with code alignment. Generalguidelines on code alignment are difficult to give, but the examples above should give a general clue.

6.3 Comments

90. Tricky code should not be commented but rewritten! [1]

In general, the use of comments should be minimized by making the code self-documenting byappropriate name choices and an explicit logical structure.

91. All comments should be written in English [2].

In an international environment English is the preferred language.


20/20


92. Use //for all comments, including multi-line comments.

/ / C o m m e n t s p a n n i n g

/ / m o r e t h a n o n e l i n e .

Since multilevel C-commenting is not supported, using // comments ensure that it is always possible tocomment out entire sections of a file using /* */ for debugging purposes etc.

There should be a space betwee n the "//" and the actual comment, and comments should always start withan upper case letter and end with a period.

93. Comments should be included relative to their position in the code. [1]

w h i l e ( t r u e ) { / / N O T : w h i l e ( t r u e ) {

/ / D o s o m e t h i n g / / D o s o m e t h i n g

s o m e t h i n g ( ) ; s o m e t h i n g ( ) ;

} }

This is to avoid that the comments break the logical structure of the program.

94. Class and method header comments should follow the JavaDoc conventions.

Regarding standardized class and method documentation the Java development community is moremature than the C/C++ one. This is due to the standard automatic Javadoc tool that is part of thedevelopment kit and that help producing high quality hypertext documentation from these comments.

There are Javadoc-like tools available al so for C++. These follows the same tagging syntax as Javadoc.See for instance Doc++ or Doxygen.

7 References

[1] Code Complete, Steve McConnel - Microsoft Press

[2] Programming in C++, Rules and Recommendations, M Henricson, e. Nyquist, Ellemtel (Swedish telecom)http://www.doc.ic.ac.uk/lab/cplus/c%2b%2b.rules/

[3] Wildfire C++ Programming Style, Keith Gabryelski, Wildfire Communications Inc.http://www.wildfire.com/~ag/Engineering/Development/C++Style/

[4] C++ Coding Standard, Todd Hoffhttp://www.possibility.com/Cpp/CppCodingStandard.htm

[5] Doxygen documentation systemhttp://www.stack.nl/~dimitri/doxygen/index.html

1998 - 2007 Geotechnical Software Services. All rights reserved.This page is maintained by [email protected]

Documents

C++ Programming Style Guidelines