PPP Style Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 10
| Download | |
| Open PDF In Browser | View PDF |
PPP Style Guide
Stroustrup
10/7/2011
PPP Style Guide
Bjarne Stroustrup
www.stroustrup.com/Programming
www.research.att.com/~bs
bs@cs.tamu.edu
Introduction
All major real-world software projects have a “house style” (“coding guide-lines”, “project standard” or
whatever they are called) to ensure clarity and consistency. This can be a nuisance because no style is
perfect, different projects have different styles, and we’d rather just write what “looks good on the day.”
However, professionals follow the approved style for a project (§25.6). This document outlines the style
we use with Programming: Principles and Practice using C++ (sometimes referred to as “PPP”).
References, such as §3.7, point to sections of PPP. More examples can be found in the model solutions to
exercises posted on the web (though the comments on those can be a bit chatty).
Stick to the simple rules outlined here. It’ll help you to read your own code and that of others and keep
you out of some minor programming problems. Your TAs are encouraged to take off points for egregious
departures from this style guide (as well as to gently guide you to improve your style – you won’t master
all immediately).
“Code as if you really mean it.” Most real-world code “lives” for a long time (years or decades) and is
read and modified repeatedly by others. Make their job more manageable by using good style. Remember,
one of those “other people” might be you.
There can be no one true style that is best for everybody everywhere, but what we recommend here is
better than anything a novice can cook up in a hurry. This is not a comprehensive style guide for major
industrial use, but it is still better than some we have seen claimed to be that.
Naming
See §3.7 for a discussion. Use a single capital letter to start a type name, e.g. Table and Temperature.
Names of non-types are not capitalized, e.g. x and var. We use underscores for multi-part names, e.g.
initial_value and symbol_tbl. Use meaningful names. Don’t overuse acronyms. Don’t use excessively
long names, such as remaining_free_slots_in_symbol_table. The length of a name should be roughly
proportional to the size of its scope (§8.4).
Be careful when using letters and digits that are easily misread: 0Oo1lL. Don’t use ALL_CAPS.
C++ identifiers are case sensitive, so Val is different from val.
~1~
PPP Style Guide
Stroustrup
10/7/2011
Indentation
Indent as done in the book. For example:
// if statement:
if (a==b) {
// …
}
else {
// …
}
// loop:
for (int i=0; i v;
// to be used in the whole of the function
string s;
// input
while (cin>>s) v.push_back(s);
}
for (int i= 0; i>s)
v.push_back(s);
~3~
PPP Style Guide
Stroustrup
10/7/2011
We use a space after a for, switch, if, or while before the (.
We do not use a space between the function name and the ( in a declaration or a call.
We use a space between class name and the { in a class declaration.
We don’t usually insert spaces in expressions, but when we do it’s to emphasize meaning (operator
binding):
if (x<0 || max<=x) // …
cin>>s;
int a = z+y*z;
We don’t use spaces in function argument lists, but we do use them in lists of argument types:
void f(int, char*, double);
f(1,"2",3.4);
In the ever-popular discussion of where to put spaces near the “pointer to” declarator operator, *, we use
the conventional C++ style:
int* p; // do it this way
int *p; // don’t
int * p; // don’t
int*p; // don’t
And when you are defining a variable, remember to initialize:
int* p = &v[i];
If you use a “smart” editor, it will have its own style, which you may or may not be able to influence.
Comments
See §7.6.4. Use comments to explain what you cannot state directly in code. Comments are for you and
your friends. Compilers don’t understand them.
Do not imitate comments in the book that explain what a language feature does – by the time you use a
feature you are supposed to know that.
Don’t say in comments what can be said clearly in code. Code is good at saying exactly what is done (in
minute detail and even if it wasn’t what you wanted it to do). Comments are good for
1. Stating intent (what is this code supposed to do)
2. Strategy (the general idea of this is …)
3. Stating invariants, pre- and post-conditions (§5.10)
If the comments and the code disagree, both are most likely wrong.
~4~
PPP Style Guide
Stroustrup
10/7/2011
You are encouraged to use intelligible English in your comments; not (say) SMS-lingo. Keep an eye on
your grammar, spelling, punctuation, and capitalization. Our aim is professionalism, not “cool.”
Start every program file (.h or .cpp) with a comment containing your name, the date, and what the
program is supposed to do. For example:
/*
*/
Joe Q. Programmer
Spring Semester 2011 (Jan 31)
Solution for exercise 6.5.
I use the technique from PPP section XX.Y.ZZ
For each non-trivial function and for each non-trivial piece of code, write a comment saying what it is
supposed to do:
// Bjarne Stroustrup 1/15/2010
// Chapter 5 Exercise 11
/*
*/
Write out Fibonacci numbers.
Find the largest Fibonacci number that fits in an int
#include "std_lib_facilities.h"
void fib()
/*
*/
{
Compute the series and note when the int overflows;
the previous value was the largest that fit
int n = 1;
int m = 2;
// element n
// element n+1
while (n make_random_numbers(int n)
// make n uniformly distributed random numbers
{
if (n<0) error("make_random_number: bad size");
vector res(n);
~6~
PPP Style Guide
}
Stroustrup
10/7/2011
// …
return res;
The point is that we don’t want to initialize res until we have checked to see that its initializer n is
acceptable for our use. So, don’t use this alternative:
vector make_random_numbers(int n)
// make n uniformly distributed random numbers
{
vector res;
// why define res when you don’t yet have a size for it?
if (n<0) error("make_random_number: bad size");
res.resize(n);
// …
return res;
}
The latter is more work and in real code putting a distance between a variable definition and its proper
initialization is an opportunity for errors to creep in.
We accept one common and important (apparent) exception to the “always initialize” rule: A variable that
is immediately used as the target for an input operation need not be explicitly initialized. For example:
int x;
cin>>x;
Even in this case, we might use an initializer so that x has a defined value if the input operation fails.
Note that objects of some types, such as string and vector are implicitly initialized. This example has no
uninitialized variables:
vector vec;
for (string buf; cin>>buf; ) vec.push_back(buf);
Don’t use “magic constants’’:
for (int i=1; i<32; ++i) {
// process a month
}
Why 32? The size of a vector? The number of days in a month plus one? Better:
const int mmax = 32;
// here we explain what 32 is and why
// …
for (int i=1; iEXIF.tools