%% LyX 1.3 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[english]{article}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{geometry}
\geometry{verbose,letterpaper,lmargin=1in,rmargin=1in}
\usepackage{array}

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
%% Because html converters don't know tabularnewline
\providecommand{\tabularnewline}{\\}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
 \newenvironment{lyxcode}
   {\begin{list}{}{
     \setlength{\rightmargin}{\leftmargin}
     \setlength{\listparindent}{0pt}% needed for AMS classes
     \raggedright
     \setlength{\itemsep}{0pt}
     \setlength{\parsep}{0pt}
     \normalfont\ttfamily}%
    \item[]}
   {\end{list}}

\usepackage{babel}
\makeatother
\begin{document}

\title{The Programming Commandments}


\author{Jayavel Shanmugasundaram}


\author{Cornell University}


\author{jai@cs.cornell.edu}


\date{7 April 2004}

\maketitle
This document outlines coding conventions that C++ developers should
follow. Some of these have been adapted from <ftp.csci.csusb.edu/cs201/commandments.txt>.
The Quark research group members provided detailed comments and feedback
on an earlier draft of this document. 


\section{Indentation and Spacing}

\begin{quotation}
\begin{tabular}{p{5.75in}}
\hline 
\emph{\char`\"{}Thou shalt indent in a consistent manner\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Each developer usually has his or her own favorite way of writing
and indenting programs. While each style may have its own potential
benefits, mixing these styles in a large code base often results in
inconsistent and awkward code. Thus, all developers should follow
the following style in writing and indenting programs.


\subsection*{Line length}

No line of code (including comments) should exceed 80 characters.
Anything larger makes it difficult to read and print out.


\subsection*{Tabbing}

Use tabs (not spaces) when writing nested statement blocks. Each indentation
should be a single tab character, and one tab width should correspond
to 4 spaces.


\subsection*{Class declarations}

\begin{lyxcode}
namespace~namespace1~\{

namespace~namespace2~\{

class~ClassName~:~public~SuperClassName~\{

public:

~~~~...

protected:

~~~~...

private:

~~~~...

\};

\};

\};
\end{lyxcode}

\subsection*{Function declarations}

Use the following style if the entire function declaration fits within
80 characters. There is a single space after \texttt{ReturnType},
\texttt{functionName}, and \texttt{ParameterType}.

\begin{lyxcode}
ReturnType~functionName~(ParameterType~param1,~const~ParameterType~param2);
\end{lyxcode}
Use the following style if the function declaration exceeds 80 characters.
Note that only one parameter declaration should appear on a line even
if more than one declaration can fit within 80 characters.

\begin{lyxcode}
ReturnType~functionName~(ParameterType~parameter1,

~~~~~~~~~~~~~~~~~~~~~~~~~const~ParameterType~parameter2,

~~~~~~~~~~~~~~~~~~~~~~~~~...

~~~~~~~~~~~~~~~~~~~~~~~~~ParameterType~parametern);
\end{lyxcode}

\subsection*{Function body}

Use the following style if the function declaration fits within 80
characters.

\begin{lyxcode}
ReturnType~functionName~(ParameterType~param1,~ParameterType~param2)~\{

~~~~Statement1

~~~~Statement2

~~~~...

~~~~Statementn

\}
\end{lyxcode}
Use the following style if the function declaration does not fit within
80 characters.

\begin{lyxcode}
ReturnType~functionName~(ParameterType~parameter1,

~~~~~~~~~~~~~~~~~~~~~~~~~ParameterType~parameter2,

~~~~~~~~~~~~~~~~~~~~~~~~~...

~~~~~~~~~~~~~~~~~~~~~~~~~ParameterType~parametern)~\{

~~~~Statement1

~~~~Statement2

~~~~...

~~~~Statementn

\}
\end{lyxcode}

\subsection*{Function invocations}

Use the following style if the function invocation fits within 80
characters. Note that there is no space between \texttt{functionName}
and \char`\"{}\texttt{(}\char`\"{}.

\begin{lyxcode}
ReturnType~result~=~functionName(parameter1,~parameter2,~,~parametern);
\end{lyxcode}
Use the following style if the function invocation does not fit within
80 characters.

\begin{lyxcode}
ReturnType~result~=~functionName(parameter1,

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~parameter2,

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~...~,

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~parametern);
\end{lyxcode}

\subsection*{If-else statement}

This template is to be used even when there is only a single statement
inside the \texttt{if}/\texttt{else} block.

\begin{lyxcode}
if~(condition)~\{

~~~~Statement1

~~~~...

~~~~Statementn

\}

else~\{

~~~~Statement1

~~~~...

~~~~Statementm

\}~
\end{lyxcode}

\subsection*{If-else-if-else statement}

\begin{lyxcode}
if~(condition1)~\{

~~~~Statement1

~~~~...

~~~~Statementn

\}

else~if~(condition2)~\{

~~~~Statement1

~~~~...

~~~~Statementm

\}

else~\{

~~~~Statement1

~~~~...

~~~~Statementp

\}
\end{lyxcode}

\subsection*{While statement}

This template is to be used even when there is only a single statement
inside the \texttt{while} block.

\begin{lyxcode}
while~(condition)~\{

~~~~Statement1

~~~~...

~~~~Statementn

\}
\end{lyxcode}

\subsection*{Do-While statement}

This template is to be used even when there is only a single statement
inside the \texttt{do}-\texttt{while} block.

\begin{lyxcode}
do~\{

~~~~Statement1

~~~~...

~~~~Statementn

\}

while~(condition);
\end{lyxcode}

\subsection*{For statement}

This template is to be used even when there is only a single statement
inside the for block.

\begin{lyxcode}
for~(IteratorType~iterator~=~0;~iterator~<~maxValue;~++iterator)~\{

~~~~Statement1

~~~~...

~~~~Statementn

\}
\end{lyxcode}

\subsection*{Switch statement}

\begin{lyxcode}
switch~(variable)~\{

~~~~case~value1:~Statement1

~~~~~~~~~~~~~~~~~...

~~~~~~~~~~~~~~~~~Statementn

~~~~~~~~~~~~~~~~~break;

~~~~...

~~~~case~valuen:~Statement1

~~~~~~~~~~~~~~~~~...

~~~~~~~~~~~~~~~~~Statementm

~~~~~~~~~~~~~~~~~break;

~~~~default:~Statement1

~~~~~~~~~~~~~...

~~~~~~~~~~~~~Statementp

~~~~~~~~~~~~~break;

\}
\end{lyxcode}

\subsection*{Try-Catch statement}

\begin{lyxcode}
try~\{

~~~~Statement1;

~~~~...

~~~~Statementm;

\}

catch~(ExceptionType\&~exceptionName1)~\{

~~~~Statement1;

~~~~...

~~~~Statementn;

\}

catch~(ExceptionType\&~exceptionName2)~\{

~~~~Statement1;

~~~~...

~~~~Statementp;

\}
\end{lyxcode}
It is \textbf{very important} that \texttt{exceptionName} be a reference
parameter; otherwise it can lead to subtle bugs when using the exception
inheritance hierarchy.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt configure your editor to use a tab size
of 4 characters\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Configure your editor so that in the display, the size of a tab is
4 characters. It is necessary to standardize the display size of a
tab character because, otherwise, what appears neatly indented on
one person's editor may appear disorganized in another person's editor.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use blank lines to separate and group logically
related sections of a program\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Use blank lines to clearly group and separate logically related parts
of the code. This makes the code more readable, and helps readers
to get a high-level overview of the code by reading the comments associated
with each group.

\underbar{Example:}

\begin{lyxcode}
ReturnType~ClassName::functionName~(ParamType~param1,~ParamType~param2)~\{



~~~~//~This~function~consists~of~two~logical~parts.~The~first~part~build~the~tree.

~~~~//~The~second~part~traverses~the~tree~and~writes~it~out~to~an~XML~file.



~~~~//~Part~I:~Building~the~tree.~This~is~done~as~follows.~

~~~~Code~for~Part~I



~~~~//~Part~II:~Traversing~and~writing~the~tree.~This~is~done~as~follows.~

~~~~Code~for~Part~II

\}~
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt leave a space after punctuation marks such
as semicolons, colons and commas\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
A space after punctuation marks makes code easy to read, just like
it does for English sentences.

\underbar{Example:}

\begin{lyxcode}
for~(int~itemIndex~=~0;~itemIndex~<~numItems;~++itemIndex)~\{

~~~~functionName(param1,~param2,~param3);

\}
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt leave a space before and after operators
such as =, <, <=, ==, +, -, {*}, and /\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
This spacing again makes code easier to read.

\underbar{Example:}

\begin{lyxcode}
largestItem~=~smallestItem~+~range;

mean~=~total~/~numItems;
\end{lyxcode}

\section{Comments and Documentation}

\begin{quotation}
\begin{tabular}{p{5.75in}}
\hline 
\emph{\char`\"{}Thou shalt write documentation before coding, and
refine it during and after coding\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Before you start writing any code, you should first write up a document
that clearly describes (a) why you are doing what you want to do,
and (b) how you are planning to do what you want to do. Item (b) should
include any relevant data structures and algorithms. You should get
the document approved by the appropriate person before you start writing
code.

There are many benefits to writing a document before you start coding.
First, it help clarify your understanding of the problem. Second,
it helps avoid \char`\"{}seat of the pants\char`\"{} programming,
whereby you just start typing in code without understanding the big
picture. Third, it help you catch pitfalls before you invest a lot
of time writing code. Finally, it gives you the opportunity to get
feedback on your design before you invest time coding.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt comment thy program while writing the code,
not as an afterthought\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Always write comments as you are writing (and modifying) code. You
will remember the rationale for your coding decisions best when you
are actually writing the code, so write the comments right there.
Comments added as an afterthought are usually superficial and hence
not very helpful. Remember, good comments are invaluable in a large
project.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt write comments at the right level of detail\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Make sure that you write comments at the right level of detail. Never
write comments for what can be directly inferred from the code (e.g.,
increment \texttt{itemIndex} by 1) - this leads to excessive and useless
comments. On the other hand, do not write comments that are too high-level
(e.g., this function traverses a tree and performs certain operations)
- these comments are not of much use to readers of the code. Writing
comments at the right level of detail is an art, and is something
that you need to strive for.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt write comments in a consistent manner\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
It is important that the commenting style be consistent throughout
the project. Thus all developers should use the following style for
commenting code.


\subsection*{Header files}

Each header file should have a comment in the header (before any \char`\"{}includes\char`\"{}
or the class declaration) that specifies relevant information about
the class being declared. In particular, the header should have the
following format.

\begin{lyxcode}
/{*}{*}

{*}~A~ClassName~object~represents~a~query~in~the~(high-level~description~of~class).

{*}

{*}~@see~RelatedClass1

{*}~@see~RelatedClass~2

{*}

{*}~@author~FirstName1~LastName1~(email@cs.cornell.edu)

{*}~@author~FirstName2~LastName2~(email@cs.cornell.edu)

{*}

{*}~@date~DateCreated~-~write~like~10~January~2003

{*}~@version~Version~of~the~code~in~which~it~was~created~(e.g.,~1.1,~2,~etc.)

{*}/
\end{lyxcode}

\subsection*{Function declarations}

Each function declaration should be commented as follows.

\begin{lyxcode}
/{*}{*}

{*}~This~function~...~(description~of~what~function~does)

{*}~

{*}~@param~Parameter1~Description~of~parameter~1

{*}~@param~Parameter2~Description~of~parameter~2

{*}

{*}~@return~What~the~function~returns

{*}

{*}~@exception~Exception1~Condition~under~which~exception~1~is~thrown

{*}~@exception~Exception2~Condition~under~which~exception~2~is~thrown

{*}

{*}~@author~FirstName1~LastName1~(email@cs.cornell.edu)

{*}~@author~FirstName2~LastName2~(email@cs.cornell.edu)

{*}

{*}~@date~DateCreated~-~write~like~10~January~2003

{*}~@version~Version~number~when~function~was~created

{*}/

ReturnType~functionName~(~...~);
\end{lyxcode}

\subsection*{Class variables}

Each class variable (private, public, or protected) should be commented
as follows.

\begin{lyxcode}
/{*}{*}

{*}~This~variable~...~(description~of~variable)

{*}/

VariableType~variableName;
\end{lyxcode}

\subsection*{Function body}

Each function body should be commented as follows.

\begin{lyxcode}
ReturnType~ClassName::functionName~()~\{

~~~~//~High-level~description~of~the~various~parts~of~the

~~~~//~function~...



~~~~//~Comments~for~each~part~of~the

~~~~//~function

~~~~Code~for~Part~I

~~~~...

\}
\end{lyxcode}
Nested parts of the function can also be commented similarly (e.g.,
inside \texttt{if} statements).


\section{Naming}

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use meaningful variable names, function
names, and class names\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Always use variable names that are meaningful. For example, if you
are iterating over all the items in an array, use a variable such
as \texttt{itemIndex} to clearly identify the loop variable. Never
use variables names such as \texttt{i}, \texttt{j}, \texttt{p}, \texttt{q},
etc. They do not mean much to readers, and are prone to misuse and
bugs. In particular, people tend to use variables such as \texttt{i}
in many places, and it is often unclear what \texttt{i} stands for,
leading to many subtle bugs. Remember that current compilers (unlike
those in the 1960s) can handle rather large variable names - take
advantage of this fact to make the variable names more readable.

The same comment also applies to function names and class names. For
example, use the function name \texttt{createSequence()} instead of
\texttt{cs()} - the former is much more readable.

\underbar{Example:} If you are iterating over items in a sequence,
use the variable \texttt{itemIndex}, not \texttt{i}.

\begin{lyxcode}
for~(int~itemIndex~=~0;~itemIndex~<~numItems;~++itemIndex)~\{

~~~~...

\}
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use consistent capitalizations for variable
names, function names, and class names\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Variable names should begin with lower case characters, and use capitalization
to separate different parts of the name. Examples are \texttt{itemIndex},
and \texttt{lastMarkedNode}.

Function names should follow the same convention as variable names.
Examples are \texttt{numItems()} and \texttt{getLastParameter()}.

Class names should begin with upper case characters, and also use
capitalization to separate different parts of the name. Examples are
\texttt{TreeNode} and \texttt{PhysicalSelectOperator}.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use file names that are consistent with
class names\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Use a file name that is consistent with the name of the class declared/defined
in the file. Declare or define only a single class in each file, unless
you are using nested classes. In the case of nested classes, make
the file name consistent with the name of the outermost class.

\underbar{Example:}

The declaration for the class \texttt{LargeVector} should be in the
file LargeVector.h

The definition of the class \texttt{LargeVector} should be in the
file LargeVector.cpp

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use declare classes to be in namespaces
that mirror the directory hierarchy\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
You should use namespaces that mirror the directory hierarchy of the
code.

\underbar{Example:}

If the class \texttt{ServerThread} is under the directory hierarchy
project/server/threadpool, then the declaration of the class \texttt{ServerThread}
should be done as follows.

\begin{lyxcode}
namespace~project~\{

namespace~server~\{

namespace~threadpool~\{

class~ServerThread~:~public~Thread~\{

~~~~...

\};

\};

\};

\};
\end{lyxcode}

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use fully qualified namespace names\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Whenever you specify a namespace, use fully qualified names (not relative
names or suffixes of fully qualified names).

\underbar{Example:}

If \texttt{quark} is the top-level namespace, \texttt{qe} is a namespace
under \texttt{quark}, and \texttt{structures} is a namespace under
\texttt{qe}, then do not use namespaces as follows:

\begin{lyxcode}
using~namespace~qe;

using~namespace~structures;
\end{lyxcode}
Instead, use fully qualified namespaces as follows:

\begin{lyxcode}
using~namespace~quark::qe;

using~namespace~quark::qe::structures
\end{lyxcode}

\begin{quotation} \begin{tabular}{p{5.75in}} \tabularnewline \hline
\emph{\char`\"{}Thou shalt use '\#ifndef' at the beginning of each header
file\char`\"{}}\tabularnewline \tabularnewline \end{tabular} \end{quotation} You
should use \texttt{\#ifndef}s at the beginning of each header ({*}.h) file in
order to avoid multiple inclusions. The \texttt{\#ifndef} variable should begin
with an underscore, be in all uppercase letters, and should correspond to the
fully qualified class name (including name space) of the class defined in the
header file.

\underbar{Example:}

The header file Server.h should be structured as follows.

\texttt{\#ifndef \_QUARK\_SERVER\_SERVER\_H}

\texttt{\#define \_QUARK\_SERVER\_SERVER\_H}

\texttt{... (contents of header file)}

\texttt{\#endif}

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt prefix all references to dynamic class
variables with 'this->'\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Always prefix all dynamic (i.e., non-static) class variables with
\texttt{this->} so that a reader can easily distinguish between a
class variable and a function parameter. This also avoids subtle bugs
whereby a function parameter is mistakenly used instead of a class
variable. This rule should also be followed in the object constructor.

\underbar{Example:}

Assume that \texttt{currentStatus} is a (private) class variable in
\texttt{ExampleClass}. Then all references to this variable in any
of \texttt{ExampleClass}'s methods should be written as:

\begin{lyxcode}
this->currentStatus~
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt prefix all references to static class variables
with the class name\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Always prefix all static class variables with the class name so that
the context of the variable is clear.

\underbar{Example:}

Assume that \texttt{staticVar} is a static class variable in \texttt{ExampleClass}.
Then all references to this variable should be written as:

\begin{lyxcode}
ExampleClass::staticVar~
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt typedef complex type declarations\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Try to avoid complex type declarations wherever possible, but if you
need to use complex type declarations, \texttt{typedef} them for readability.

\underbar{Example:}

To declare a template type \texttt{Queue<Message<IPAddress> >}, use
the following \texttt{typedef}:

\begin{lyxcode}
typedef~Queue<Message<IPAddress>~>~IPMessageQueue;
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use enumerated types wherever possible\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Whenever you have a parameter or value with a finite number of meaningful
alternatives, use enumerated types. They make the code much more readable,
and enable static type checking for invalid values. Always use uppercase
letters to declare \texttt{enum} names, and use \char`\"{}\_\char`\"{}
to separate words if necessary.

\underbar{Example:}

If you wish to pass a parameter to a function that either clones or
reuses an object, do not use a Boolean value such as: \texttt{functionName(...,
true)} or \texttt{functionName(..., false)}. Instead, declare an enum
as follows:

\begin{lyxcode}
enum~\{CLONE,~DO\_NOT\_CLONE\};
\end{lyxcode}
Use this \texttt{enum} in functions as follows: \texttt{functionName(...,
CLONE)} or \texttt{functionName(..., DO\_NOT\_CLONE)}. This usage
is much more readable than passing in Boolean values. The same observation
also applies to integers, strings and other types.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt declare all constants in a component header
file using 'const' declarations\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Never hardcode constants in a program. If you use a constant in a
function body, you are most likely doing something wrong. It sometimes
makes sense to define constants in a class header, but in many cases,
it is good to define constants in a header file that is global for
a given component (this makes constants easy to track and change).
Use the \texttt{const} modifier to declare constants; do not use \texttt{\#define}
for this purpose because it can lead to subtle bugs. Use uppercase
letters for constant names, and use \char`\"{}\_\char`\"{} to separate
words if necessary.

\underbar{Example:}

To define the maximum size of a query string, define a constant as
follows.

\begin{lyxcode}
const~int~MAX\_QUERY\_STRING\_SIZE~=~1000000;
\end{lyxcode}

\section{Objects and Abstraction}

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt pass all parameters necessary for object
creation in the object constructor\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Whenever you create an object, pass all the parameters necessary for
creating the object in the constructor. Never create a \char`\"{}partial\char`\"{}
object in the constructor with some missing data items, and later
use \texttt{setParameter()} to fill in the missing data items. Passing
in all parameters necessary for object creation in the constructor
leads to cleaner code, and ensures that you will have a valid object.
Otherwise, you may potentially have an invalid object which can lead
to many errors.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt check for object integrity in the object
constructor\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Always check for the integrity of the object in the constructor. At
the end of object creation, all other object methods should be able
to assume that the object is in a consistent state. Thus awkward checks
can be avoided in each object method.

\underbar{Example:}

If a parameter/field is not supposed to be \texttt{NULL}, raise an
error in the constructor.

If the set of parameters passed to the constructor is inconsistent
(i.e., no object can be created with that particular combination of
parameters), raise an error.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt ensure that each class method maintains
the integrity of the object\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Just as the constructor creates an object that is in a consistent
state, ensure that each class method also leaves the object in a consistent
state. This way, each object method can just focus on reading and
transforming the object from one consistent state to another.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use data abstraction in each class\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Never expose the \char`\"{}internals\char`\"{} of an object - make
such attributes private fields. Do not add public accessor methods
for internal fields that should not be exposed to higher layers. For
example, if you have a field \texttt{unusedMemory} that is \char`\"{}internal\char`\"{}
to an object, do not add accessor methods called \texttt{getUnusedMemory()}
and \texttt{setUnusedMemory()}. This essentially makes \texttt{unusedMemory}
a public field, which is not what is desired. Instead, initialize
this field in the constructor and modify it as necessary in the public
methods that preserve data abstraction. 

Note that some times it is acceptable to write public accessor methods
for private fields so long as they preserve data abstraction. For
example, if \texttt{currentStatus} is an abstract property of an object,
you may wish to create a \texttt{currentStatus} private field, and
add the accessor methods \texttt{getCurrentStatus()} and \texttt{setCurrentStatus()}.
You need to judge when adding accessor methods preserves or violates
data abstraction, and use accessor methods judiciously.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt be consistent in naming object accessor
methods\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Use a consistent naming policy for object accessor methods.

\underbar{Example:}

All accessor methods should be prefixed with a \char`\"{}get\char`\"{}.

\begin{lyxcode}
getSize();

getParameter~(int~position);
\end{lyxcode}

\section{Stylistic Issues}

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt declare and initialize variables just before
their use\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Always declare variables just before you are about to use them, and
initialize them at this declaration point. Never declare a whole bunch
of variables at the beginning of a function, and then use them at
different points in the function. The advantages of declaring variables
just before using them are (a) it is easy to see what the variable
is for - very few humans have the ability to glean the significance
of 20 or so variables declared in one chunk at the header of a function,
and (b) it allows variables to be initialized on declaration because
the initial value may depend on the current context, and (c) it results
in cleaner code because useless variables are not left hanging around
in the beginning of the function. 

Earlier languages such as C did not support variable declarations
inside the function body, but modern languages such as C++ and Java
support this feature - make full use of it.

\underbar{Example:} If you need to use a loop variable, initialize
it just before use.

\begin{lyxcode}
for~(int~itemIndex~=~0;~itemIndex~<~numItems;~++itemIndex)~\{

~~~...

\}
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt write simple statements in the code\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Do not write complicated statements in the code. Each statement should
be simple and self-evident. Nesting function calls and array dereferences
is one of the easiest ways to write complicated code, and this should
be avoided.

\underbar{Examples:}

Do not write code that looks like this:

\begin{lyxcode}
int~currentItem~=~firstArray{[}secondArray{[}thirdArray{[}index{]},~fourthArray{[}index{]}{]}{]};
\end{lyxcode}
Instead, write the code as follows:

\begin{lyxcode}
int~thirdArrayItem~=~thirdArray{[}index{]};

int~fourthArrayItem~=~fourthArray{[}index{]};

int~secondArrayItem~=~secondArray{[}thirdArrayItem,~fourthArrayItem{]};

int~currentItem~=~firstArray{[}secondArrayItem{]};
\end{lyxcode}
Do not write code that looks like this:

\begin{lyxcode}
Item~currentItem~=~functionCall1(functionCall2(functionCall3(index)->getChild(i)));
\end{lyxcode}
Instead, write the code as follows:

\begin{lyxcode}
Item~childItem~=~functionCall3(index)->getChild(i);

Item~parentItem~=~functionCall2(childItem);

Item~currentItem~=~functionCall3(parentItem);
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use the modifier 'const' to declare immutable
parameters\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Always declare immutable parameters (i.e., parameters whose value
cannot be changed by a function) to be 'const' parameters.

\underbar{Example:}

The \texttt{strlen()} function should not change the contents of its
input string. Thus, it is declared as:

\begin{lyxcode}
int~strlen~(const~char~{*}str);
\end{lyxcode}
Another example is:

\begin{lyxcode}
int~searchForClosestRelative~(const~Person~{*}person);
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use the modifier 'const' to declare member
functions that do not modify an object\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Always declare functions that do not modify an object as \texttt{const}
functions. This enables the compiler to perform static type checking
for \texttt{const} parameters.

\underbar{Example:}

\begin{lyxcode}
class~Person~\{

public:

~~~boolean~isAlive~()~const;

\}
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use the modifier 'const' when a function
returns an object that should not be modified.\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Again, this enables the compiler to perform static type checking for
\texttt{const} parameters.

\underbar{Example:}

\begin{lyxcode}
class~Person~\{

public:

~~~~const~Person\&~getBestFriend~()~const;

\}
\end{lyxcode}
\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt not write long functions\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Do not write long functions that go on for pages and pages. A good
rule of thumb is to ensure that the body of a function does not exceed
a page of printed text. Break down long functions into calls to well-defined
smaller functions.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt not inline a function body in a header
file\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Do not inline a function body in a header file, even if the function
body is just one line. Header files are specification of what the
class does, and should not contain implementation details.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt not use global variables\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
This should be self-explanatory.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt not use goto statements\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
This should be self-explanatory too. If not, read Dijkstra's \char`\"{}The
Go To Statement Considered Harmful\char`\"{} <http://www.acm.org/classics/oct95/>. 


\section{Error Handling}

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use exceptions for handling errors\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Structure your code so that it uses exceptions for handing errors.
This is much cleaner than checking for an error code after every function
invocation.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use comments to specify the exceptions
thrown by a function\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
You should include the exceptions thrown by a function in your comments
so that higher-level functions can use this information to appropriately
recover from the exceptions. Please see Section 2 for the specific
details on the format of the comments.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt not use the 'throw' clause in the function
declaration\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
C++ does not have static type checking for the exceptions thrown by
the function. For example, consider a function \texttt{f} that throws
an exception \texttt{MyException} either directly or indirectly (by
invoking another function that throws \texttt{MyException}). If you
declare a \texttt{throw} clause for \texttt{f} and forget to include
\texttt{MyException}, the compiler will not complain. However, when
\texttt{MyException} is actually thrown, your program will be terminated
because an exception not specified in the \texttt{throw} clause is
actually thrown. In other words, C++ checks exception declarations
dynamically during code execution, but not statically. Hence, it is
very difficult (if not impossible) to statically verify the correctness
of function signatures.

To avoid this problem, you should not declare a \texttt{throw} clause
for a function. This means that the function can throw any exception,
and you will never get an abnormal program termination. Your top-level
function can catch \char`\"{}all\char`\"{} exceptions and handle this
in whatever way is best for the application. You should still declare
the exceptions thrown by a function in the documentation (see conventions
above) so that higher-level functions can catch specific exceptions
if necessary.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt use an inheritance hierarchy for exceptions\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Use a natural inheritance hierarchy for exceptions. For example, define
a root \texttt{Exception} class from which all other exceptions are
derived. Then define a derived exception class for each logical part
of the program, for example \texttt{ParserException}, \texttt{EvaluatorException},
etc. If need be, you can further derive exception for each sub-part.
For example, you can derive \texttt{EvaluatorStructuresException}
and \texttt{EvaluatorRuntimeException} from \texttt{EvaluatorException}.

\begin{quotation}
\begin{tabular}{p{5.75in}}
\tabularnewline
\hline 
\emph{\char`\"{}Thou shalt name exceptions in a consistent manner\char`\"{}}\tabularnewline
\tabularnewline
\end{tabular}
\end{quotation}
Suffix each exception class with \texttt{Exception}. This makes it
easier to identify exception classes.

\underbar{Examples:}

\begin{lyxcode}
EvaluatorException

EvaluatorRuntimeException\end{lyxcode}

\end{document}
