1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/doc/codingstd.tex Fri Aug 25 09:02:29 2006 +0200
1.3 @@ -0,0 +1,544 @@
1.4 +\documentclass[11pt]{article}
1.5 +\usepackage{times}
1.6 +\setlength{\textwidth}{6.5in}
1.7 +\setlength{\textheight}{9in}
1.8 +\setlength{\oddsidemargin}{0.0in}
1.9 +\setlength{\evensidemargin}{0.0in}
1.10 +\setlength{\topmargin}{-0.5in}
1.11 +\def\nst{{\em ns--3}}
1.12 +\begin{document}
1.13 +\begin{center}
1.14 +{\Large Coding Standard for ns--3}\\
1.15 +Revision A \\
1.16 +August 22, 2005
1.17 +
1.18 +\end{center}
1.19 +\section{Introduction}
1.20 +This document describes the coding standard to be used by the \nst\
1.21 +project. All contributed software for \nst\ should follow this
1.22 +style, which will result in consistent and easy to read code. A set
1.23 +of emacs macros and a emacs startup file will be provided to assist
1.24 +with creating software following this standard.
1.25 +
1.26 +\section{Standards}
1.27 +\subsection{General}
1.28 +\begin{enumerate}
1.29 +\item There will be no {\em tab} characters in the code. Rather, repeated
1.30 +spaces are used to separate the characters as needed.
1.31 +\item No line of code will be longer than 80 characters in length, to
1.32 +prevent lines wrapping in the {\tt emacs} or {\tt vi} editors. For both
1.33 +of these linux text editing tools, the default is a window that is
1.34 +exactly 80 characters wide, so if none of the lines wrap when editing
1.35 +in {\tt emacs} or {\tt vi} this requirement is met.
1.36 +
1.37 +\item Each C++ statement will be on a separate line. The only exception
1.38 +is when an {\tt if}, {\tt else}, {\tt for} or {\tt while}
1.39 +statement has a single
1.40 +statement sub--block these can be on the same line.
1.41 +
1.42 +Examples:
1.43 +
1.44 +\begin{tt}
1.45 +int i = 0; // Right\\
1.46 +i = 10; j = 20; // Wrong. Two statements same line\\
1.47 +Sub1(k); Sub2(k); // Wrong. Two statements same line\\
1.48 +if (done) break; // Right. If statement with single statement sub-block
1.49 +\end{tt}
1.50 +
1.51 +\item Each variable declaration will be on a separate line.
1.52 +
1.53 +Examples:
1.54 +
1.55 +\begin{tt}
1.56 +\begin{tabbing}
1.57 +int c, d; \=// Wrong. c and d defined on same line.\\
1.58 +int a = 0; \\
1.59 +int b = 0; \>// Right. a and b on different lines\\
1.60 +\end{tabbing}
1.61 +\end{tt}
1.62 +
1.63 +\item Variables should be declared at the point in the code
1.64 +where they are needed, and should be assigned an initial value
1.65 +at the time of declaration.
1.66 +
1.67 +\begin{tt}
1.68 +\begin{tabbing}
1.69 +int a = 0; \=// Right, a is assigned in initial value.\\
1.70 +int b; \> Wrong, b is not assigned an initial value.\\
1.71 +int c = 0; \\
1.72 +int d = Sub1(a, b);\\
1.73 +c = Sub2(d); \> // Wrong, c should be declared here, not above
1.74 +\end{tabbing}
1.75 +\end{tt}
1.76 +
1.77 +\item Excepting when used in a {\tt switch} statement, the open
1.78 +and close curly braces (\{ and \}) are always on a separate line.
1.79 +
1.80 +Examples:
1.81 +\begin{tt}
1.82 +\begin{tabbing}
1.83 +aa\=aa\=aa\= \kill
1.84 +for (int i = 0; i < MAX\_COUNT; ++i) \\
1.85 +\>\{ // Right. Open brace on separate line \\
1.86 +\>\>sum += i; \\
1.87 +\>\>prod *= i; \\
1.88 +\>\} // Right. Close brace on separate line
1.89 +\end{tabbing}
1.90 +\end{tt}
1.91 +
1.92 +\begin{tt}
1.93 +\begin{tabbing}
1.94 +aa\=aa\=aa\= \kill
1.95 +for (int i = 0; i < 10; ++i) \{ // Wrong. Open brace on same line\\
1.96 +\>sum += i; \\
1.97 +\>prod *= i; \} // Wrong. Close brace on same line
1.98 +\end{tabbing}
1.99 +\end{tt}
1.100 +
1.101 +\item The C++ {\tt goto} statement is not to be used.
1.102 +\end{enumerate}
1.103 +\subsection{Commenting}
1.104 +In general, comments should be use liberally throughout the program to
1.105 +increase readability. Specifically:
1.106 +
1.107 +\begin{enumerate}
1.108 +\item C++ style comments using the {\tt //} delimeter
1.109 +are to be used, rather than C style comments with the {\tt /*}
1.110 +and {\tt */} delimieters.
1.111 +
1.112 +\item Variable declaration should have a short, one or two line comment
1.113 +describing the purpose of the variable, unless it is a
1.114 +local variable whose use is obvious from the context. The short
1.115 +comment should be on the same line as the variable declaration, unless it
1.116 +is too long, in which case it should be on the preceding lines.
1.117 +
1.118 +Example:
1.119 +
1.120 +\begin{tt}
1.121 +int averageGrade; // Computed average grade for this project \\
1.122 + // Note. The above comment likely qualifies as \\
1.123 + // obvious from context, and could be omitted.
1.124 +\\
1.125 +// Counts the total number of students completing the project, but\\
1.126 +// does not include those not turning in the project. \\
1.127 +int projectCount = 0;
1.128 +\end{tt}
1.129 +\item Every function should be preceded by a detailed comment block
1.130 +describing what the function does, what the formal parameters are, and
1.131 +what the return value is (if any).
1.132 +
1.133 +\item Every class declaration should be preceded by a comment block
1.134 +describing what the class is to be used for.
1.135 +
1.136 +\item Unless obvious from context, each {\tt if} statement should
1.137 +include a one--line comment on the open curly brace following describing
1.138 +the {\tt TRUE} condition and the {\tt FALSE} condition.
1.139 +
1.140 +Example:
1.141 +
1.142 +\begin{tt}
1.143 +\begin{tabbing}
1.144 +aa\=aa\=aa\= \kill
1.145 +if (iter == students.end()) \\
1.146 +\>\{ // Student not found, add him \\
1.147 +\>\>students.push\_back(thisStudent); \\
1.148 +\>\} \\
1.149 +else \\
1.150 +\>\{ // Student exists, modify existing data \\
1.151 +\>\>iter->grade += thisGrade; \\
1.152 +\>\}
1.153 +\end{tabbing}
1.154 +\end{tt}
1.155 +\item Class and function comments should adhere to the Doxygen standard
1.156 +format, for automated extraction by the Doxygen tool. {\em Note from
1.157 +GFR. We need a bit more here, as Doxygen has several possible methods
1.158 +for commenting. I'll look them over and suggest an approach, for later
1.159 +discussion}
1.160 +
1.161 +\end{enumerate}
1.162 +\subsection{Naming Conventions}
1.163 +\begin{enumerate}
1.164 +\item {\bf Variable Names}. All variables, including global variables,
1.165 +local variables, formal parameters,
1.166 +and member variables in classes will start with a
1.167 +lower case letter, and consist of only alphabetic characters and numeric
1.168 +digits. Capital letters are to be used when appropriate between words
1.169 +in a variable name for increased readability.
1.170 +Variable names should not contain the underscore character.
1.171 +The variable name should
1.172 +be descriptive of the use of the variable, excepting for temporary
1.173 +local variables where the function is obvious from the context (for example
1.174 +loop index variables are commonly a single letter such as {\tt i}).
1.175 +
1.176 +Examples:
1.177 +
1.178 +{\tt int i;}\\
1.179 +{\tt int nextIndexValue;}\\
1.180 +{\tt int sum1;}\\
1.181 +{\tt int loopCount10;}
1.182 +
1.183 +\item {\bf Subroutine Names}. All subroutine names, including global
1.184 +routines and member functions in classes, will start with an upper case
1.185 +letter, and consist of only alphabetic characters and numeric digits
1.186 +(although digits should be rarely needed).
1.187 +As in variable names, upper case letters are to be used between words as needed
1.188 +to increase readability.
1.189 +
1.190 +Examples:
1.191 +
1.192 +{\tt int ComputeNextIterator()}\\
1.193 +{\tt int Calculate()}\\
1.194 +{\tt int TransmitPacket()}\\
1.195 +{\tt int Dummy()}
1.196 +
1.197 +\item {\bf Defined Constants}. All defined constants will be all upper
1.198 +case letters or numeric digits, with the underscore character separating
1.199 +words.
1.200 +
1.201 +Examples:
1.202 +
1.203 +{\tt typedef enum \{ PACKET\_RX, PACKET\_FIRST\_BIT\_RX, PACKET\_TX\} }\\
1.204 +{\tt \#define NUMBER\_ELEMENTS 10}\\
1.205 +{\tt const int LOOP\_COUNT = 100}
1.206 +
1.207 +\item {\bf Defined Types}. All user defined types will end start with
1.208 +an upper case letter, consist of upper and lower case letters only, and
1.209 +end in {\tt \_t}.
1.210 +
1.211 +Examples:
1.212 +
1.213 +{\tt typedef double Time\_t; // Simulation time}\\
1.214 +{\tt typedef unsigned long SimulatorUid\_t; // Unique ID for each event}\\
1.215 +{\tt typedef unsigned long Event\_t; // Idenifies events in handler}\\
1.216 +
1.217 +\item {\bf Class Names}. Class names will start with an upper case letter,
1.218 +consist of only alphabetic characters, and include capital letters as
1.219 +needed to increase readability.
1.220 +
1.221 +Examples:
1.222 +
1.223 +{\tt class DropTailQueue \{}\\
1.224 +{\tt class Ferrari \{}\\
1.225 +
1.226 +\end{enumerate}
1.227 +
1.228 +%\newpage % Adjust as needed
1.229 +\subsection{Statement Formatting}
1.230 +\begin{enumerate}
1.231 +\item {\bf Indention}. The basic indention level for all code
1.232 +is four character positions. In some cases, indention to ``one--half''
1.233 +level, is required as described below.
1.234 +\item {\bf Continuation statements}. Frequently a single statement
1.235 +is too long to fit within a single 80 column line. In this case, the
1.236 +statement is simply continued on the next one or more lines. Each
1.237 +continuation line must be indented at least one--half indention level,
1.238 +and more as necessary to increase readability.
1.239 +
1.240 +Examples:
1.241 +
1.242 +\begin{tt}
1.243 +\begin{tabbing}
1.244 +longVariableName = \=(anotherLongName * shorterName) + (loopIndex2 * i) + \\
1.245 +\>(k * j); // Correct, indented for neatness
1.246 +\end{tabbing}
1.247 +\end{tt}
1.248 +
1.249 +\begin{tt}
1.250 +\begin{tabbing}
1.251 +a\=a\=a\= \kill
1.252 +for (LongTypeName\_t longLoopIndexName = aLongExpression; \\
1.253 +\>longLoopIndexName < MAX\_VALUE; \\
1.254 +\>longLoopIndexName++) // Wrong, continuations not indented far enough
1.255 +\end{tabbing}
1.256 +\end{tt}
1.257 +
1.258 +\begin{tt}
1.259 +\begin{tabbing}
1.260 +for (\=LongTypeName\_t longLoopIndexName = aLongExpression; \\
1.261 +\>longLoopIndexName < MAX\_VALUE; \\
1.262 +\>longLoopIndexName++) // Right, indented for readability
1.263 +\end{tabbing}
1.264 +\end{tt}
1.265 +
1.266 +\item {\bf {\tt IF} Statements}.
1.267 +The open curly brace following an {\tt IF} statement must be on the
1.268 +following line, indented by one--half indention level.
1.269 +The subsequent lines must
1.270 +indented an additional one--half indention level.
1.271 +{\tt IF} statements with only
1.272 +one statement in either the {\tt TRUE} of {\tt FALSE} sub--blocks
1.273 +may omit the curly braces. The {\tt ELSE} statement (if present)
1.274 +must be on a line by itself.
1.275 +
1.276 +Examples:
1.277 +
1.278 +\begin{tt}
1.279 +\begin{tabbing}
1.280 +aa\=aa\=aa\= \kill
1.281 +if (someCondition) \\
1.282 +\>\{ // Describe TRUE condition here\\
1.283 +\>\>i = k;\\
1.284 +\>\>k = i + 2;\\
1.285 +\>\} // Right, curly block indented one-half, statements one-half more
1.286 +\end{tabbing}
1.287 +\end{tt}
1.288 +
1.289 +\begin{tt}
1.290 +\begin{tabbing}
1.291 +aa\=aa\=aa\= \kill
1.292 +if (someCondition) \\
1.293 +\>\{ // Describe TRUE condition here\\
1.294 +\>\>i = k;\\
1.295 +\>\>k = i + 2;\\
1.296 +\>\} \\
1.297 +else // Right, ELSE statement on separate line, same indent as IF \\
1.298 +\>\{ // Describe FALSE condition here\\
1.299 +\>\>i = k * 2; \\
1.300 +\>\>k = i + 4; \\
1.301 +\>\} // Right, closing curly brace lined up with open brace
1.302 +\end{tabbing}
1.303 +\end{tt}
1.304 +
1.305 +\begin{tt}
1.306 +\begin{tabbing}
1.307 +aa\=aa\=aa\= \kill
1.308 +if (someCondition) // Describe TRUE condition here\\
1.309 +\>i = k; // Right, single line block need not have curly braces \\
1.310 +\end{tabbing}
1.311 +\end{tt}
1.312 +
1.313 +\begin{tt}
1.314 +if (someCondition) i = k; // Right, single statement may be on same line
1.315 +\end{tt}
1.316 +
1.317 +\item {\bf {\tt FOR} Statements}.
1.318 +The open brace following a {\tt for} statement is indented
1.319 +one-half level from the {\tt for} statement itself. Each statement
1.320 +in the sub--block is indented one--half level from the curly brace.
1.321 +If the sub--block is a single statement, the curly braces can be
1.322 +omitted and the statement indented one level, or optionally appear
1.323 +on the same line as the {\tt for} statement.
1.324 +
1.325 +Example:
1.326 +
1.327 +\begin{tt}
1.328 +\begin{tabbing}
1.329 +aa\=aa\=aa\= \kill
1.330 +for (int i = 0; i < MAX\_COUNT; ++i) \\
1.331 +\>\{ // Curly brace indented one-half level \\
1.332 +\>\>sum += i; // Statements indented another one-half level \\
1.333 +\>\>prod *= i; \\
1.334 +\>\} // Close brace on same column as open brace \\
1.335 +\end{tabbing}
1.336 +\end{tt}
1.337 +
1.338 +\begin{tt}
1.339 +for (int i = 0; i < MAX\_COUNT; ++i) Sub1(i); // Right, single statement\\
1.340 +\end{tt}
1.341 +
1.342 +\item {\bf {\tt WHILE} Statements}.
1.343 +{\tt While} statements are formatted similarly to {\tt IF} statements,
1.344 +with curly braces indented one-half level on separate lines, and the
1.345 +inner statements indented another half-level. If the sub--block has only
1.346 +a single line, the curly braces can be omitted, and the statement may
1.347 +appear on the same line as the {\tt WHILE} statement.
1.348 +
1.349 +Examples:
1.350 +
1.351 +\begin{tt}
1.352 +\begin{tabbing}
1.353 +aa\=aa\=aa\= \kill
1.354 +while (someCondition) \\
1.355 +\>\{ // Right, open brace indented one-half level \\
1.356 +\>\>i = k; // Right, statements indented one-half level from open brace \\
1.357 +\>\>k = i + 2;\\
1.358 +\>\} // Right, close brace lines up with open brace
1.359 +\end{tabbing}
1.360 +\end{tt}
1.361 +
1.362 +\begin{tt}
1.363 +while (someCondition) i = i + 2; // Right, single stmt on same line
1.364 +\end{tt}
1.365 +
1.366 +\item {\bf Infinite Loops}.
1.367 +Any loop intended to be infinite (of course with a {\tt break} statement
1.368 +somewhere) should be of the form:
1.369 +
1.370 +\begin{tt}
1.371 +while(true) \\
1.372 + { // Loop until sentinel found\\
1.373 + ...code here \\
1.374 + }
1.375 +\end{tt}
1.376 +
1.377 +\item {\bf {\tt SWITCH} Statements}.
1.378 +The open curly brace for a {\tt switch} statement will be on the same
1.379 +line as the {\tt switch} statement itself. Each {\tt case} statement
1.380 +following is indented two columns from the switch statement. Each
1.381 +statement in the {\tt case} block is indented two column from the
1.382 +{\tt case} statement. The closing curly brace is on a separate line
1.383 +by itself, indented two columns from the {\tt switch} statement.
1.384 +
1.385 +Example:
1.386 +
1.387 +\begin{tt}
1.388 +\begin{tabbing}
1.389 +aa\=aa\=aa\= \kill
1.390 +switch(someCondition) \{ Right, open brace on same line as switch\\
1.391 +\>case 0 : // Right, case indented two columns from switch\\
1.392 +\>\>i = k; // Right, statements indented two columns from case \\
1.393 +\>\>k = i + 2;\\
1.394 +\>\>break;\\
1.395 +\>case 1 : // Right, case indented two columns from switch\\
1.396 +\>\>i = k + 2; // Right, statements indented two columns from case \\
1.397 +\>\>k = i + 4;\\
1.398 +\>\>break;\\
1.399 +\>\} // Right, close brace lines up with case statements
1.400 +\end{tabbing}
1.401 +\end{tt}
1.402 +
1.403 +\item {\bf Functions}. Since C and C++ do not allow nested functions,
1.404 +all functions start with no indentation at column 0. The open curly
1.405 +brace is on a line by itself immediately following the function header
1.406 +and formal parameters, also in column 0. Any local variable declarations
1.407 +immediately following the open curly brace also start at column 0.
1.408 +One blank line follows the initial local variable declarations (if any).
1.409 +The statements in the function body are indented one-half level
1.410 +from the curly brace. Any variable declarations after the start of the
1.411 +statements are indented at the same level as the preceding statement.
1.412 +The closing brace is at column 0.
1.413 +
1.414 +Example:
1.415 +
1.416 +\begin{tt}
1.417 +\begin{tabbing}
1.418 +aa\=aa\=aa\=aa\= \kill
1.419 +void Function1(int arg1, double arg2)\\
1.420 +\{ // Right, curly brace at column 0\\
1.421 +int local1 = 0; // Right, local variable at column 0\\
1.422 +int local2;\\
1.423 +\>\\
1.424 +\>local2 = local1 + arg1 + arg2; // Right, indented two columns\\
1.425 +\>int local3; // Right, variable at same level\\
1.426 +\>local3 = Function2(local2);\\
1.427 +\>if (someCondition)\\
1.428 +\>\>\{\\
1.429 +\>\>\>local3 = 0;\\
1.430 +\>\>\>local2 = local1;\\
1.431 +\>\>\>int local4 = local1 + 1; // Right, variable at same level\\
1.432 +\>\>\>Function3(local4);\\
1.433 +\>\>\}\\
1.434 +\} // Right, close brace at column 0
1.435 +\end{tabbing}
1.436 +\end{tt}
1.437 +
1.438 +\item {\bf Expressions}. Spaces should be used liberally in expressions
1.439 +to increase readability. One space before and after each operator,
1.440 +excepting the increment and decrement operators, leads to easy--to--read
1.441 +expressions. Continued expressions should be indented as far as needed
1.442 +for neatness and readability.
1.443 +
1.444 +Examples:
1.445 +
1.446 +\begin{tt}
1.447 +i = k * 2 + 3 / var1++; // Right, spacing separating terms \\
1.448 +\end{tt}
1.449 +
1.450 +\begin{tt}
1.451 +i = k*2+2/var1++; // Wrong, crowded together and hard to read
1.452 +\end{tt}
1.453 +
1.454 +\begin{tt}
1.455 +\begin{tabbing}
1.456 +someLongVariableName = \=anotherLongVariableName * shorterName + \\
1.457 +\>anotherName; // Right, indented to line up
1.458 +\end{tabbing}
1.459 +\end{tt}
1.460 +
1.461 +\end{enumerate}
1.462 +\subsection{Header Files}
1.463 +\begin{enumerate}
1.464 +\item All header files will have a file name ending with {\tt .h}.
1.465 +\item All header files should have a one line comment describing
1.466 +the purpose of the header, and comments identifying the
1.467 +author and the (approximate) date the file was created.
1.468 +
1.469 +Example:
1.470 +
1.471 +\begin{tt}
1.472 +// ns3 Network Simulator - TCP Base Class Declaration \\
1.473 +// George F. Riley. riley@ece.gatech.edu. \\
1.474 +// Georgia Tech, Fall 2006
1.475 +\end{tt}
1.476 +
1.477 +\item All header files should have an ``include guard'' to prevent accidental
1.478 +inclusion of the file multiple times in a single compilation unit.
1.479 +
1.480 +Example:
1.481 +
1.482 +\begin{tt}
1.483 +\#ifndef \_\_tcp\_h\_\_ \\
1.484 +\#define \_\_tcp\_h\_\_ \\
1.485 +
1.486 +// (Contents of tcp.h here
1.487 +
1.488 +\#endif
1.489 +\end{tt}
1.490 +\item Header files should avoid including other files whenever possible.
1.491 +This can often be avoided with judicious use of the
1.492 +{\tt class ClassName;} forward declaration.
1.493 +
1.494 +Example:
1.495 +
1.496 +\begin{tt}
1.497 +// excerpt from application.h \\
1.498 +class L4Protocol; \\
1.499 +
1.500 +class Application \{ \\
1.501 + .... \\
1.502 + AddL4Proto(const L4Protocol\&); \\
1.503 + .... \\
1.504 + L4Protocol* l4Proto; \\
1.505 +\};
1.506 +\end{tt}
1.507 +
1.508 +In the above example, the use of the forward declaration for {\tt L4Protocol}
1.509 +obviates the need to include {\tt l4proto.h} in the application header
1.510 +file.
1.511 +
1.512 +\end{enumerate}
1.513 +\subsection{Source Code Files}
1.514 +\begin{enumerate}
1.515 +\item All souce code files will have a file name ending with {\tt .cc}.
1.516 +\item All source code files should have a one line comment describing
1.517 +the purpose of the code, and comments identifying the
1.518 +author and the (approximate) date the file was created.
1.519 +
1.520 +Example:
1.521 +
1.522 +\begin{tt}
1.523 +// ns3 Network Simulator - TCP Base Class Implementation \\
1.524 +// George F. Riley. riley@ece.gatech.edu. \\
1.525 +// Georgia Tech, Fall 2006
1.526 +\end{tt}
1.527 +
1.528 +\item All {\tt \#include} directives should be grouped with {\em system}
1.529 +files listed first (eg. {\tt \#include <iostream>}), followed by
1.530 +\nst\ defined files (eg. {\tt \#include "tcp.h"}). Within a group,
1.531 +the includes should be sorted in alphabetical order.
1.532 +
1.533 +Example:
1.534 +
1.535 +\begin{tt}
1.536 +\#include <iostream> \\
1.537 +\#include <list> \\
1.538 +\#include <vector> \\
1.539 +
1.540 +\#include "application.h" \\
1.541 +\#include "dumbbell.h" \\
1.542 +\#include "simulator.h" \\
1.543 +\#include "tcp.h.h"
1.544 +
1.545 +\end{tt}
1.546 +\end{enumerate}
1.547 +\end{document}