--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/codingstd.tex Fri Aug 25 09:02:29 2006 +0200
@@ -0,0 +1,544 @@
+\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.
+
+Example:
+
+\begin{tt}
+\#include <iostream> \\
+\#include <list> \\
+\#include <vector> \\
+
+\#include "application.h" \\
+\#include "dumbbell.h" \\
+\#include "simulator.h" \\
+\#include "tcp.h.h"
+
+\end{tt}
+\end{enumerate}
+\end{document}