CS201 - Introduction To Programming Handout: C Programming Style Guide - Part I
CS201 - Introduction To Programming Handout: C Programming Style Guide - Part I
CS201 - Introduction To Programming Handout: C Programming Style Guide - Part I
Table of Contents:
Introduction........................................................................................................................................................ 3
1.1 Layout of the Recommendations............................................................................................................. 3
Naming Conventions ......................................................................................................................................... 3
2.1 General Naming Conventions ................................................................................................................. 3
2.2 Specific Naming Conventions.................................................................................................................. 4
Files ................................................................................................................................................................... 5
3.1 Source Files............................................................................................................................................. 5
3.2 Include Files and Include Statements...................................................................................................... 5
Statements ........................................................................................................................................................ 6
4.1 Variables.................................................................................................................................................. 6
4.2 Loops ....................................................................................................................................................... 7
4.3 Conditionals ............................................................................................................................................. 7
4.4 Miscellaneous .......................................................................................................................................... 8
Layout and Comments ...................................................................................................................................... 9
5.1 Layout ...................................................................................................................................................... 9
5.2 White Space .......................................................................................................................................... 12
5.3 Comments ............................................................................................................................................. 13
Introduction
This document lists C/C++ coding recommendations common in the C/C++ development
community.
While a given development environment (IDE) can improve the readability of code by
access visibility, color coding, automatic formatting and so on, the programmer should
never rely on such features. Source code should always be considered larger than the IDE
it is developed within and should be written in a way that maximize its readability
independent of any IDE.
Naming Conventions
2.1 General Naming Conventions
• Variable names must be in mixed case starting with lower case.
• size, employeeName
• It makes variables easy to distinguish from types, and effectively resolves
potential naming collision.
• Named constants must be all uppercase using underscore to separate words.
• COLOR_RED, PI.
• Names representing methods or functions must be verbs and written in mixed case
starting with lower case.
• getName(), computeTotalSalary(). This is identical to variable names.
• Abbreviations and acronyms must not be uppercase when used as name.
• exportHtmlSource(); // NOT: exportHTMLSource();
openDvdPlayer(); // NOT: openDVDPlayer();
• Variables with a large scope should have long names, variables with a small scope
can have short names.
• Scratch variables used for temporary storage or indices are best kept short. A
programmer reading such variables should be able to assume that its value is not
used outside a few lines of code. Common scratch variables for integers are i, j, k,
m, n and for characters c and d.
2.2 Specific Naming Conventions
Files
3.1 Source Files
• C/C++ header files should have the extension .h. Source files can have the
extension .c or .cpp.
• MyFile.cpp, MyFile.h
• 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.
• File content must be kept within 80 columns per line.
• 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.
• Special characters like TAB and page break must be avoided.
• These characters are bound to cause problem for editors, printers, terminal
emulators or debuggers when used in a multi-programmer, multi-platform
environment.
• The incompleteness of split lines must be made obvious.
• totalSum = a + b + c +
d + e;
Split lines occurs when a statement exceed the 80 column limit given above. It is
difficult to give rigid rules for 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.
3.2 Include Files and Include Statements
• Include statements should be sorted and grouped. Sorted by their hierarchical
position in the system with low level files included first. Leave an empty line
between groups of include statements.
#include <fstream>
#include <iomanip>
#include <Xm/Xm.h>
#include <Xm/ToggleB.h>
#include "ui/PropertiesDialog.h"
#include "ui/MainWindow.h"
In addition to show the reader the individual include files, it also give an
immediate clue about the modules that are involved.
Include file paths must never be absolute. Compiler directives should instead be
used to indicate root directories for includes.
• Include statements must be located at the top of a file only.
• Avoid unwanted compilation side effects by "hidden" include statements deep
into a source file.
Statements
4.1 Variables
• 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 a valid value where it is declared:
int x, y, z;
getCenter (&x, &y, &z);
In these cases it should be left uninitialized rather than initialized to some phony
value.
• Variables must never have dual meaning.
• Enhance readability by ensuring all concepts are represented uniquely. Reduce
chance of error by side effects.
• Use of global variables should be minimized.
• In C/C++ there is no reason global variables need to be used at all. The same is
true for global functions or file scope (static) variables.
• Related variables of the same type can be declared in a common statement.
Unrelated variables should not be declared in the same statement.
float x, y, z;
float revenueJanuary, revenueFebruary, revenueMarch;
The common requirement of having declarations on separate lines is not useful in
the situations like the ones above. It enhances readability to group variables like
this.
• C/C++ pointers and references should have their reference symbol next to the
variable name rather than to the type name.
• float *x; // NOT: float* x;
int &y; // NOT: int& y;
• The const keyword should be listed before the type name.
• void f1 (const int *x) // NOT: void f1 (int const *x)
• Implicit test for 0 should not be used.
• if (nLines != 0) // NOT: if (nLines)
if (value != 0.0) // NOT: if (value)
• 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 effects of the variable.
4.2 Loops
• Only loop control statements must be included in the for() construction.
• sum = 0; // NOT: for (i = 0, sum = 0; i < 100; i++)
for (i = 0; i < 100; i++) // sum += value[i];
sum += value[i];
Increase maintainability and readability. Make it crystal clear what controls the
loop and what the loop contains.
• Loop variables should be initialized immediately before the loop.
• isDone = false; // NOT: bool isDone = false;
while (!isDone)
{ // while (!isDone)
: // {
} // :
// }
4.3 Conditionals
// Better!
fileHandle = open (fileName, "w");
if (!fileHandle)
{
:
}
Conditionals with executable statements are just very difficult to read. This is
especially true for programmers new to C/C++.
4.4 Miscellaneous
• The use of magic numbers in the code should be avoided. Numbers other than 0
and 1 should be considered declared as named constants instead.
• If the number does not have an obvious meaning by itself, the readability is
enhanced by introducing a named constant instead. A different approach is to
introduce a method from which the constant can be accessed.
• Floating point constants should always be written with decimal point and at least
one decimal.
• double total = 0.0; // NOT: double total = 0;
double speed = 3.0e8; // NOT: double speed = 3e8;
double sum;
:
sum = (a + b) * 10.0;
This emphasize the different nature of integer and floating point numbers even if
their values might happen to be the same in a specific case. Also, as in the last
example above, it emphasize the type of the assigned variable (sum) at a point in
the code where this might not be evident.
• Floating point constants should always be written with a digit before the decimal
point.
• double total = 0.5; // NOT: double total = .5;
• The number and expression system in C/C++ is borrowed from mathematics and
one should adhere to mathematical conventions for syntax wherever possible.
Also, 0.5 is a lot more readable than .5; There is no way it can be mixed with the
integer 5.
• Functions must always have the return value explicitly listed.
• int getValue() // NOT: getValue()
{
:
}
If not explicitly listed, C/C++ implies int return value for functions. A
programmer must never rely on this feature, since this might be confusing for
programmers not aware of this artifact.
• goto statement should not be used.
• goto statements violates the idea of structured code. Only in some very few cases
(for instance breaking out of deeply nested structures) should goto be considered,
and only if the alternative structured counterpart is proven to be less readable.
if (condition)
{
statements;
}
else
{
statements;
}
if (condition)
{
statements;
}
else if (condition)
{
statements;
}
else
{
statements;
}
The first approach is considered better in the way that each part of the if-else
statement is written on separate lines of the file. This should make it easier to
manipulate the statement, for instance when moving else clauses around.
case DEF :
statements;
break;
case XYZ :
statements;
break;
default :
statements;
break;
}
Note that each case keyword is indented relative to the switch statement as a whole.
This makes the entire switch 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 break statement. Leaving the break out is a common error,
and it must be made clear that it is intentional when it is not there.
• Single statement if-else, for or while statements can be written without brackets.
• if (condition)
statement;
while (condition)
statement;
for (initialization; condition; update)
statement;
It is a common recommendation that brackets should always be used in all these
cases. However, brackets are in general a language construct that groups several
statements. Brackets are per definition superfluous on a single statement.
Note: The starting curly brace can be put at the end of the construct or on the new
line.
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. General guidelines on code alignment are difficult to give, but the
examples above should give a general clue.
5.3 Comments
/*****************************************************************
* FILE NAME:
*
*
*
* PURPOSE:
*
*
*
* EXTERNAL VARIABLES:
*
* Source: < >
*
*
*
* Name Type I/O Description
*
* ---- ---- --- -----------
*
*
*
* ABNORMAL TERMINATION CONDITIONS
*
*
*
* ERROR AND WARNING MESSAGES:
*
*
*
* ASSUMPTIONS, CONSTRAINTS, RESTRICTIONS:
*
*
*
* NOTES:
*
*
*
* DEVELOPMENT HISTORY:
*
*
*
* Date Author Change Id Release Description Of Change
*
* ---- ------ ---------- -------- ------------- *
*
*
*****************************************************************/