\documentclass[11pt]{article}

\usepackage{times}

\setlength{\textwidth}{6.5in}

\setlength{\textheight}{9in}

\setlength{\oddsidemargin}{0.0in}

\setlength{\evensidemargin}{0.0in}

\setlength{\topmargin}{-0.5in}

\def\nst{{\em ns--3}}

\newcommand{\code}[1]{\texttt{#1}}

\begin{document}

\begin{center}

{\Large Coding Standard for ns--3}\\

August 22, 2005

\end{center}

\section{Introduction}

The purpose of the \nst\ project is to build software which will last

many years: making sure that the code is readable and stays so is 

one of the most important items required to achieve this goal. This

document thus outlines guidelines we plan to enforce on each component

integrated in \nst to ensure uniformity of the codebase which is

a first step towards readable code.

\section{Recommendations}

The following recommendations are not strict rules and some of them

are conflicting but the point here is to outline the fact that we

value more common-sense than strict adherence to the coding style

defined in this document.

\subsection{naming}

Types, methods, functions and variable names should be self-descriptive. 

Avoid using acronyms, expand them, do not hesitate to use long names,

Avoid shortcuts such as \code{sz} for \code{size}. Long names sometimes get in the 

way of being able to read the code:

\begin{verbatim}

for (int loopCount = 0; loopCount < max; loopCount++) 

  {

    // code

  }

\end{verbatim}

loopCount should be renamed to something shorter such as 

\code{i}, \code{j}, \code{k}, \code{l}, \code{m}, and \code{n} 

which are widely used names which identify loop counters:

\begin{verbatim}

for (int i = 0; i < max; i++) 

  {

    // code

  }

\end{verbatim}

Similarly, \code{tmp} is a common way to denote temporary variables. On

the other hand, \code{foo} is not an appropriate name: it says nothing

about the purpose of the variable.

If you use predicates (that is, functions, variables or methods

which return a single boolean value), prefix the 

name with \code{is} or \code{has}.

\subsection{Memory management}

As much as possible, try to pass around objects

by value and allocate them on the stack. If you need to allocate

objects on the heap with new, make sure that the corresponding

call to delete happens where the new took place. i.e., avoid

passing around pointer ownership.

Avoid the use of reference counting and, more generaly, strive to

keep the memory-management model simple.

\subsection{Templates}

For now, templates are defined only in the simulator

core and are used everywhere else. Try to keep it that way by 

avoiding defining new templates in model-specific code.

\section{Standards}

\subsection{General}

\begin{enumerate}

\item There will be no {\em tab} characters in the code.  Rather, repeated

spaces are used to separate the characters as needed.

\item No line of code will be longer than 80 characters in length, to

prevent lines wrapping in the {\tt emacs} or {\tt vi} editors.  For both

of these linux text editing tools, the default is a window that is

exactly 80 characters wide, so if none of the lines wrap when editing

in {\tt emacs} or {\tt vi} this requirement is met.

\item Each C++ statement will be on a separate line.  The only exception

is when an {\tt if}, {\tt else}, {\tt for} or {\tt while}

statement has a single

statement sub--block these can be on the same line.

Examples:

\begin{tt}

int i = 0; // Right\\

i = 10; j = 20;   // Wrong. Two statements same line\\

Sub1(k); Sub2(k); // Wrong. Two statements same line\\

if (done) break;  // Right. If statement with single statement sub-block

\end{tt}

\item Each variable declaration will be on a separate line.

Examples:

\begin{tt}

\begin{tabbing}

int c, d; \=// Wrong.  c and d defined on same line.\\

int a = 0;    \\

int b = 0;    \>// Right.  a and b on different lines\\

\end{tabbing}

\end{tt}

\item Variables should be declared at the point in the code

where they are needed, and should be assigned an initial value

at the time of declaration.

\begin{tt}

\begin{tabbing}

int a = 0;          \=// Right, a is assigned in initial value.\\

int b; \> Wrong, b is not assigned an initial value.\\

int c = 0; \\

int d = Sub1(a, b);\\

c = Sub2(d); \> // Wrong, c should be declared here, not above

\end{tabbing}

\end{tt}

\item Excepting when used in a {\tt switch} statement, the open

and close curly braces (\{ and \}) are always on a separate line.

Examples:

\begin{tt}

\begin{tabbing}

aa\=aa\=aa\= \kill

for (int i = 0; i < MAX\_COUNT; ++i) \\

\>\{             // Right.  Open brace on separate line \\

\>\>sum += i;                                           \\

\>\>prod *= i;                                          \\

\>\}             // Right.  Close brace on separate line

\end{tabbing}

\end{tt}

\begin{tt}

\begin{tabbing}

aa\=aa\=aa\= \kill

for (int i = 0; i < 10; ++i) \{ // Wrong.  Open brace on same line\\

\>sum += i;                                                       \\

\>prod *= i; \}                 // Wrong.  Close brace on same line

\end{tabbing}

\end{tt}

\item The C++ {\tt goto} statement is not to be used.

\end{enumerate}

\subsection{Commenting}

In general, comments should be use liberally throughout the program to

increase readability.  Specifically:

\begin{enumerate}

\item C++ style comments using the {\tt //} delimeter

are to be used, rather than C style comments with the {\tt /*}

and {\tt */} delimieters.

\item Variable declaration should have a short, one or two line comment

describing the purpose of the variable, unless it is a 

local variable whose use is obvious from the context. The short

comment should be on the same line as the variable declaration, unless it

is too long, in which case it should be on the preceding lines.

Example:

\begin{tt}

int averageGrade;  // Computed average grade for this project \\

                   // Note. The above comment likely qualifies as \\

                   // obvious from context, and could be omitted.

\\

// Counts the total number of students completing the project, but\\

// does not include those not turning in the project. \\

int projectCount = 0;

\end{tt}

\item Every function should be preceded by a detailed comment block

describing what the function does, what the formal parameters are, and

what the return value is (if any).

\item Every class declaration should be preceded by a comment block

describing what the class is to be used for.

\item Unless obvious from context, each {\tt if} statement should 

include a one--line comment on the open curly brace following describing

the {\tt TRUE} condition and the {\tt FALSE} condition.

Example:

\begin{tt}

\begin{tabbing}

aa\=aa\=aa\= \kill

if (iter == students.end()) \\

\>\{ // Student not found, add him \\

\>\>students.push\_back(thisStudent); \\

\>\} \\

else \\

\>\{ // Student exists, modify existing data \\

\>\>iter->grade += thisGrade; \\

\>\}

\end{tabbing}

\end{tt}

\item Class and function comments should adhere to the Doxygen standard

format, for automated extraction by the Doxygen tool.  {\em Note from

GFR. We need a bit more here, as Doxygen has several possible methods

for commenting.  I'll look them over and suggest an approach, for later

discussion}

\end{enumerate}

\subsection{Naming Conventions}

\begin{enumerate}

\item {\bf Variable Names}.  All variables, including global variables,

local variables, formal parameters, 

and member variables in classes will start with a

lower case letter, and consist of only alphabetic characters and numeric

digits.  Capital letters are to be used when appropriate between words

in a variable name for increased readability.  

Variable names should not contain the underscore character.

Examples:

{\tt int i;}\\

{\tt int nextIndexValue;}\\

{\tt int sum1;}\\

{\tt int loopCount10;}

\item {\bf Subroutine Names}.  All subroutine names, including global

routines and member functions in classes, will start with an upper case

letter, and consist of only alphabetic characters and numeric digits

(although digits should be rarely needed).

As in variable names, upper case letters are to be used between words as needed

to increase readability.

Examples:

{\tt int ComputeNextIterator()}\\

{\tt int Calculate()}\\

{\tt int TransmitPacket()}\\

{\tt int Dummy()}

\item {\bf Defined Constants}.  All defined constants will be all upper

case letters or numeric digits, with the underscore character separating

words.  

Examples:

{\tt typedef enum \{ PACKET\_RX, PACKET\_FIRST\_BIT\_RX, PACKET\_TX\} }\\

{\tt \#define NUMBER\_ELEMENTS 10}\\

{\tt const int LOOP\_COUNT = 100}

\item {\bf Defined Types}.  All user defined types will end start with

an upper case letter, consist of upper and lower case letters only, and

end in {\tt \_t}.

Examples:

{\tt typedef double         Time\_t;         // Simulation time}\\

{\tt typedef unsigned long  SimulatorUid\_t; // Unique ID for each event}\\

{\tt typedef unsigned long  Event\_t;        // Idenifies events in handler}\\

\item {\bf Class Names}.  Class names will start with an upper case letter,

consist of only alphabetic characters, and include capital letters as 

needed to increase readability.

Examples:

{\tt class DropTailQueue \{}\\

{\tt class Ferrari \{}\\

\end{enumerate}

%\newpage % Adjust as needed

\subsection{Statement Formatting}

\begin{enumerate}

\item {\bf Indention}.  The basic indention level for all code

is four character positions.  In some cases, indention to ``one--half''

level, is required as described below.

\item {\bf Continuation statements}.  Frequently a single statement

is too long to fit within a single 80 column line.  In this case, the

statement is simply continued on the next one or more lines.  Each

continuation line must be indented at least one--half indention level,

and more as necessary to increase readability.  

Examples:

\begin{tt}

\begin{tabbing}

longVariableName = \=(anotherLongName * shorterName) + (loopIndex2 * i) + \\

\>(k * j); // Correct, indented for neatness

\end{tabbing}

\end{tt}

\begin{tt}

\begin{tabbing}

a\=a\=a\= \kill

for (LongTypeName\_t longLoopIndexName = aLongExpression; \\

\>longLoopIndexName < MAX\_VALUE; \\

\>longLoopIndexName++) // Wrong, continuations not indented far enough

\end{tabbing}

\end{tt}

\begin{tt}

\begin{tabbing}

for (\=LongTypeName\_t longLoopIndexName = aLongExpression; \\

\>longLoopIndexName < MAX\_VALUE; \\

\>longLoopIndexName++) // Right, indented for readability

\end{tabbing}

\end{tt}

\item {\bf {\tt IF} Statements}.

The open curly brace following an {\tt IF} statement must be on the

following line, indented by one--half indention level.

The subsequent lines must

indented an additional one--half indention level.

{\tt IF} statements with only

one statement in either the {\tt TRUE} of {\tt FALSE} sub--blocks

may omit the curly braces.  The {\tt ELSE} statement (if present)

must be on a line by itself.

Examples:

\begin{tt}

\begin{tabbing}

aa\=aa\=aa\= \kill

if (someCondition) \\

\>\{ // Describe TRUE condition here\\

\>\>i = k;\\

\>\>k = i + 2;\\

\>\} // Right, curly block indented one-half, statements one-half more

\end{tabbing}

\end{tt}

\begin{tt}

\begin{tabbing}

aa\=aa\=aa\= \kill

if (someCondition) \\

\>\{ // Describe TRUE condition here\\

\>\>i = k;\\

\>\>k = i + 2;\\

\>\} \\

else  // Right, ELSE statement on separate line, same indent as IF \\

\>\{ // Describe FALSE condition here\\

\>\>i = k * 2; \\

\>\>k = i + 4; \\

\>\}   // Right, closing curly brace lined up with open brace

\end{tabbing}

\end{tt}

\begin{tt}

\begin{tabbing}

aa\=aa\=aa\= \kill

if (someCondition) // Describe TRUE condition here\\

\>i = k; // Right, single line block need not have curly braces \\

\end{tabbing}

\end{tt}

\begin{tt}

if (someCondition) i = k; // Right, single statement may be on same line

\end{tt}

\item {\bf {\tt FOR} Statements}.

The open brace following a {\tt for} statement is indented

one-half level from the {\tt for} statement itself.  Each statement

in the sub--block is indented one--half level from the curly brace.

If the sub--block is a single statement, the curly braces can be 

omitted and the statement indented one level, or optionally appear

on the same line as the {\tt for} statement.

Example:

\begin{tt}

\begin{tabbing}

aa\=aa\=aa\= \kill

for (int i = 0; i < MAX\_COUNT; ++i) \\

\>\{             // Curly brace indented one-half level \\

\>\>sum += i;    // Statements indented another one-half level \\

\>\>prod *= i;                                          \\

\>\}             // Close brace on same column as open brace \\

\end{tabbing}

\end{tt}

\begin{tt}

for (int i = 0; i < MAX\_COUNT; ++i) Sub1(i); // Right, single statement\\

\end{tt}

\item {\bf {\tt WHILE} Statements}.

{\tt While} statements are formatted similarly to {\tt IF} statements,

with curly braces indented one-half level on separate lines, and the

inner statements indented another half-level. If the sub--block has only

a single line, the curly braces can be omitted, and the statement may

appear on the same line as the {\tt WHILE} statement.

Examples:

\begin{tt}

\begin{tabbing}

aa\=aa\=aa\= \kill

while (someCondition) \\

\>\{ // Right, open brace indented one-half level \\

\>\>i = k; // Right, statements indented one-half level from open brace \\

\>\>k = i + 2;\\

\>\}       // Right, close brace lines up with open brace

\end{tabbing}

\end{tt}

\begin{tt}

while (someCondition) i = i + 2; // Right, single stmt on same line

\end{tt}

\item {\bf Infinite Loops}.

Any loop intended to be infinite (of course with a {\tt break} statement

somewhere) should be of the form:

\begin{tt}

while(true) \\

  { // Loop until sentinel found\\

    ...code here \\

  }

\end{tt}

\item {\bf {\tt SWITCH} Statements}.

The open curly brace for a {\tt switch} statement will be on the same

line as the {\tt switch} statement itself.  Each {\tt case} statement

following is indented two columns from the switch statement.  Each

statement in the {\tt case} block is indented two column from the

{\tt case} statement.  The closing curly brace is on a separate line

by itself, indented two columns from the {\tt switch} statement.

Example:

\begin{tt}

\begin{tabbing}

aa\=aa\=aa\= \kill

switch(someCondition) \{ Right, open brace on same line as switch\\

\>case 0 : // Right, case indented two columns from switch\\

\>\>i = k; // Right, statements indented two columns from case \\

\>\>k = i + 2;\\

\>\>break;\\

\>case 1 : // Right, case indented two columns from switch\\

\>\>i = k + 2; // Right, statements indented two columns from case \\

\>\>k = i + 4;\\

\>\>break;\\

\>\}       // Right, close brace lines up with case statements

\end{tabbing}

\end{tt}

\item {\bf Functions}.  Since C and C++ do not allow nested functions,

all functions start with no indentation at column 0.  The open curly

brace is on a line by itself immediately following the function header

and formal parameters, also in column 0.  Any local variable declarations

immediately following the open curly brace also start at column 0.

One blank line follows the initial local variable declarations (if any).

The statements in the function body are indented one-half  level 

from the curly brace.  Any variable declarations after the start of the

statements are indented at the same level as the preceding statement.

The closing brace is at column 0.

Example:

\begin{tt}

\begin{tabbing}

aa\=aa\=aa\=aa\= \kill

void Function1(int arg1, double arg2)\\

\{               // Right, curly brace at column 0\\

int local1 = 0;  // Right, local variable at column 0\\

int local2;\\

\>\\

\>local2 = local1 + arg1 + arg2;   // Right, indented two columns\\

\>int local3;                      // Right, variable at same level\\

\>local3 = Function2(local2);\\

\>if (someCondition)\\

\>\>\{\\

\>\>\>local3 = 0;\\

\>\>\>local2 = local1;\\

\>\>\>int local4 = local1 + 1;     // Right, variable at same level\\

\>\>\>Function3(local4);\\

\>\>\}\\

\}               // Right, close brace at column 0

\end{tabbing}

\end{tt}

\item {\bf Expressions}.  Spaces should be used liberally in expressions

to increase readability.  One space before and after each operator,

excepting the increment and decrement operators, leads to easy--to--read

expressions.  Continued expressions should be indented as far as needed

for neatness and readability.

Examples:

\begin{tt}

i = k * 2 + 3 / var1++;  // Right, spacing separating terms \\

\end{tt}

\begin{tt}

i = k*2+2/var1++;        // Wrong, crowded together and hard to read

\end{tt}

\begin{tt}

\begin{tabbing}

someLongVariableName = \=anotherLongVariableName * shorterName + \\

\>anotherName;  // Right, indented to line up

\end{tabbing}

\end{tt}