diff --git a/doc/codingstd.tex b/doc/codingstd.tex deleted file mode 100644 index 8845f6248..000000000 --- a/doc/codingstd.tex +++ /dev/null @@ -1,592 +0,0 @@ -\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 Class Member and Global Variables}. To be able to distinguish -local variables from class member and global variables, prepend the -\code{m\_} prefix to class member variables and the \code{g\_} prefix -to global variables. - -Examples: -\begin{verbatim} -class Foo { -private: - int m_myPrivateVar; -}; -static int g_myGlobalVar; -\end{verbatim} - -\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 two character positions. -\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 indention level. -The subsequent lines must be -indented by an additional one indention level. -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 indent level, statements one indent 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} - - -\item {\bf {\tt FOR} Statements}. -The open brace following a {\tt for} statement is indented -one level from the {\tt for} statement itself. Each statement -in the sub--block is indented one 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 level \\ -\>\>sum += i; // Statements indented another one level \\ -\>\>prod *= i; \\ -\>\} // Close brace on same column as open brace \\ -\end{tabbing} -\end{tt} - -\item {\bf {\tt WHILE} Statements}. -{\tt While} statements are formatted similarly to {\tt IF} statements, -with curly braces indented one level on separate lines, and the -inner statements indented another 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 level \\ -\>\>i = k; // Right, statements indented one level from open brace \\ -\>\>k = i + 2;\\ -\>\} // Right, close brace lines up with open brace -\end{tabbing} -\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. - -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 2\\ -\>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. The include -guard should be named after the file name. If the file name is \code{foo-bar.h}, then the -include guard should be named \code{FOO\_BAR\_H} - -Example: - -\begin{tt} -\#ifndef FOO\_BAR\_H \\ -\#define FOO\_BAR\_H \\ - -// (Contents of foo-bar.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 }), 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 \\ -\#include \\ -\#include \\ - -\#include "application.h" \\ -\#include "dumbbell.h" \\ -\#include "simulator.h" \\ -\#include "tcp.h.h" - -\end{tt} -\end{enumerate} -\end{document}