C++ Coding Guidelines v1.07

1. Introduction

1.1   To use C++ in your website project, you MUST obtain prior agreement from your project manager at the BBC. This is because C++ is rarely used on bbc.co.uk so the BBC does not have the environment to easily support it.

1.2 This section describes some standard practices when coding in C++ for BBC website projects. Some are common practice, others might initially seem unnecessary, but they encourage clarity and readability in code and avoid idioms that can give rise to common bugs.

Top of page

2. General style

2.1 You SHOULD use the Object Oriented features of C++ as much as possible. If you are constantly casting things or doing IsKindOf calls on objects, then your design is probably wrong.

2.2 You should protect your data. All member variables SHOULD be protected and only accessible (where appropriate) via methods. Furthermore, you SHOULD avoid exposing details of implementation that might change. Supply a feature set of methods that could, if necessary, have an entirely different implementation or platform.

2.3 You SHOULD use ASSERTs in debug code.

2.4 You SHOULD avoid allocating memory on the heap. If you must, however, make sure it is explicit in the object design where objects need to be deleted and whose responsibility it is. Use try/catch blocks where you are allocating memory on the heap and clean up after exceptions.

2.5 You SHOULD program defensively. Anticipate breakages. Always test your code, especially with boundary conditions. Consider writing tests before you write your code (the XP way).

Top of page

3. Source file organisation

3.1 You SHOULD use one file per class where practical. Small helper classes that are ‘local' to a major class can be incorporated in the same file but you should use separate files if the code gets too large.

3.2 You SHOULD name source files after the class name they implement and omit the leading 'C'. For example, the class Cwidget will reside in the files Widget.cpp and Widget.h.

3.3 You SHOULD put functions in the CPP files. In this way, they are more likely to get updated when the function is updated than if they were all in the class definition.

Top of page

4. Hungarian notation

4.1 We prefer to use some Hungarian notation to indicate the type of a variable in its name. Names SHOULD start with one or more lower-case letters to indicate the type of variable. For example:

• iCount – int
• bCompleted – bool
• sNameOfTag – string (i.e. string class)
• pThing – pointer (can be combined with the others to indicate a pointer to a specific type, but we don't often do this).
• ppThing – pointer to a pointer.

4.2 Otherwise, you SHOULD use studly caps to separate words, not underscores. The first letter (excluding the type identifier) should be in caps.

Top of page

5. Global variables and constants

5.1 Constants (usually implemented by #define) SHOULD be all upper case with words separated by underscores, for example, ALLOWED_CHARS.

5.2 You SHOULD NOT use global variables (with obvious exceptions, like the sole instance of your primary object). They are a source of bugs, and can usually be avoided. If you do need to use global variables, you SHOULD prefix their names with 'g_' (for instance, g_iTotalHits).

Top of page

6. Class comments

6.1 Each class SHOULD have a similar block comment preceding with Author, Date, and description. The description should give any specific instantiation or initialisation notes, and where possible, usage examples.

Top of page

7. Class naming convention

7.1 Class names SHOULD start with 'C' and use studly caps to break up words. Use descriptive class names like CUserPageBuilder or CArticleList.

7.2 You SHOULD NOT use underscores in class names.

Top of page

8. Member variables

8.1 Member variables of a class SHOULD be prefixed with m_' but otherwise should use the conventions above. For example:

• int m_iAccessCount;
• CString m_sDeviceName;

8.2 There is no specific convention for local, private, or protected variables.

8.3 You SHOULD declare local variables as close to their first use as scope allows, and always initialise variables to a known initial value.

Top of page

9. Method naming

9.1 Methods SHOULD use studly caps and should always start with a capital.

9.2 For example, if you have methods to get or set properties of your class, use GetSomeProperty and SetSomeProperty. For Boolean properties, IsSomeState is a better choice than Get.

Top of page

10. Statements

10.1 Each line SHOULD contain at most one statement – do not use multi-statement lines.

10.2 An if statement SHOULD always have braces.

10.3 You SHOULD avoid the question mark (?) operator – use an if statement instead for clarity.

10.4 You SHOULD avoid the following testing pointer validity syntax:

if (pThing) or if (!pThing)

Rather, use the explicit syntax:

if (pThing != NULL) or if (pThing == NULL)

10.5 You SHOULD avoid assignments in conditional statements.

10.6 When using switch statements, you SHOULD explicitly comment any deliberate fall-through behaviour (where you deliberately omit the break from the end of a case clause).

Top of page

11. Comments

11.1 You SHOULD use slashes (//) for comments that are inside functions. You SHOULD put comments on their own lines, indented with the code, rather than on the same line as the code, to avoid long lines. Use comments to explain why an action/procedure is required. What you are doing should be obvious from the code itself.

11.2 For commenting function definitions, you SHOULD use block comments /* ... */.

11.3 A comment should preferably look like this:

/******************

Void SomeFunction(int iValue)
Author: Fred Bloggs
Created: 21st Feb 2002
Inputs: iValue – Value to process
Outputs: - 
Returns: - 
Purpose: Performs a blinovitch transformation on iValue 
and stores it in the output queue.

******************/

11.4 You SHOULD NOT use #if 0 to comment out blocks of code, as most syntax colourers cannot find it.

Top of page

12. Brace style

12.1 Braces SHOULD be on a separate line, and align with their opening statement.

So this is correct:

if (bCondition)
{
   CallSomeFunction(sName);
   while (GetValue())
   {
       DoSomething();
   }
}
else
{
   Report("Failed");
}

12.2 Additionally, you SHOULD always use braces, even for single statements, so rather than this:

if (bTest)
   DoSomething();

you should do this:

if (bTest)
{
   DoSomething();
}

All this is doing is making your intentions explicit. This is generally a good rule to follow.

Top of page

13. White space

13.1 You SHOULD use tabs rather than spaces (four tab stops are recommended).

13.2 Blank lines SHOULD always be introduced in these places:

• Between header comments and the start of the function definition
• Between function definitions or class declarations
• After any large block comments (but not necessarily after every comment)

13.3 You SHOULD avoid lines longer than 80 characters.

13.4 You SHOULD break up long lists of parameters, indenting the broken lines to the right of the start of the first line.

For example:

CallFunction(BigName, AnotherParameter, GoshThisIsLong);

becomes:

CallFunction(BigName,
   AnotherParameter,
   GoshThisIsLong);

13.5 You SHOULD break up long strings into quotes on single lines – the pre-processor will concatenate them for you.

For example:

LongMessage = "This is a really really long message 
that ought to have been broken up";

becomes:

LongMessage = "This is a really really long message"
   " that ought to have been broken up";

13.6 You SHOULD remember to preserve necessary spaces.

Top of page

14. Document history

Date	Version	Change	Author
08/03/2005	v1.07	Added "not supported..." paragraph to the intro	Sally Underwood
04/03/2003	v1.06	Added bookmarks to all headings for easier reference from browser	Jonathan Hassell
19/08/2002	v1.05	Added audience into footer	Jonathan Hassell
17/08/2002	v1.04	Checked all contacts are abstracted into contacts file	Jonathan Hassell
16/08/2002	v1.03	Renamed as appendix B. Checked doc for all inter-document links.	Jonathan Hassell
15/08/2002	v1.02	Slight reorganisation corrections, and Done global search for MUST, SHOULD etc	Jonathan Hassell
07/08/2002	v1.01	Added copyright information to footer	Jonathan Hassell
06/08/2002	v1.00	Promoted these standards from old app3	Jonathan Hassell

Top of page