F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

george's draft of a coding std

Browse Source
This commit is contained in:
Mathieu Lacage
2006-08-25 09:02:29 +02:00
parent cf2d2395f6
commit 2166f86e80
1 changed files with 544 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

544
doc/codingstd.tex Normal file
View File

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