\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}}

\begin{document}

\begin{center}

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

Revision A \\

August 22, 2005

\end{center}

\section{Introduction}

This document describes the coding standard to be used by the \nst\

project.  All contributed software for \nst\ should follow this

style, which will result in consistent and easy to read code.  A set

of emacs macros and a emacs startup file will be provided to assist

with creating software following this standard.

\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.

The variable name should

be descriptive of the use of the variable, excepting for temporary

local variables where the function is obvious from the context (for example

loop index variables are commonly a single letter such as {\tt i}).

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}

\end{enumerate}

\subsection{Header Files}

\begin{enumerate}

\item All header files will have a file name ending with {\tt .h}.

\item All header files should have a one line comment describing

the purpose of the header, and comments identifying the

author and the (approximate) date the file was created.

Example:

\begin{tt}

// ns3 Network Simulator - TCP Base Class Declaration \\

// George F. Riley.  riley@ece.gatech.edu. \\

// Georgia Tech, Fall 2006

\end{tt}

\item All header files should have an ``include guard'' to prevent accidental

inclusion of the file multiple times in a single compilation unit.

Example:

\begin{tt}

\#ifndef \_\_tcp\_h\_\_  \\

\#define \_\_tcp\_h\_\_ \\

// (Contents of tcp.h here

\#endif

\end{tt}

\item Header files should avoid including other files whenever possible.

This can often be avoided with judicious use of the

{\tt class ClassName;} forward declaration.  

Example:

\begin{tt}

// excerpt from application.h \\

class L4Protocol; \\

class Application \{ \\

 .... \\

 AddL4Proto(const L4Protocol\&); \\

 .... \\

 L4Protocol* l4Proto; \\

\};

\end{tt}

In the above example, the use of the forward declaration for {\tt L4Protocol}

obviates the need to include {\tt l4proto.h} in the application header

file.

\end{enumerate}

\subsection{Source Code Files}

\begin{enumerate}

\item All souce code files will have a file name ending with {\tt .cc}.

\item All source code files should have a one line comment describing

the purpose of the code, and comments identifying the

author and the (approximate) date the file was created.

Example:

\begin{tt}

// ns3 Network Simulator - TCP Base Class Implementation \\

// George F. Riley.  riley@ece.gatech.edu. \\

// Georgia Tech, Fall 2006 

\end{tt}

\item All {\tt \#include} directives should be grouped with {\em system}

files listed first (eg. {\tt \#include <iostream>}), followed by

\nst\ defined files (eg. {\tt \#include "tcp.h"}).  Within a group,

the includes should be sorted in alphabetical order.