1.1 --- a/doc/codingstd.tex	Fri Aug 25 09:02:29 2006 +0200
     1.2 +++ b/doc/codingstd.tex	Fri Aug 25 09:52:48 2006 +0200
     1.3 @@ -6,19 +6,75 @@
     1.4  \setlength{\evensidemargin}{0.0in}
     1.5  \setlength{\topmargin}{-0.5in}
     1.6  \def\nst{{\em ns--3}}
     1.7 +\newcommand{\code}[1]{\texttt{#1}}
     1.8 +
     1.9  \begin{document}
    1.10  \begin{center}
    1.11  {\Large Coding Standard for ns--3}\\
    1.12 -Revision A \\
    1.13  August 22, 2005
    1.14  
    1.15  \end{center}
    1.16  \section{Introduction}
    1.17 -This document describes the coding standard to be used by the \nst\
    1.18 -project.  All contributed software for \nst\ should follow this
    1.19 -style, which will result in consistent and easy to read code.  A set
    1.20 -of emacs macros and a emacs startup file will be provided to assist
    1.21 -with creating software following this standard.
    1.22 +
    1.23 +The purpose of the \nst\ project is to build software which will last
    1.24 +many years: making sure that the code is readable and stays so is 
    1.25 +one of the most important items required to achieve this goal. This
    1.26 +document thus outlines guidelines we plan to enforce on each component
    1.27 +integrated in \nst to ensure uniformity of the codebase which is
    1.28 +a first step towards readable code.
    1.29 +
    1.30 +\section{Recommendations}
    1.31 +
    1.32 +The following recommendations are not strict rules and some of them
    1.33 +are conflicting but the point here is to outline the fact that we
    1.34 +value more common-sense than strict adherence to the coding style
    1.35 +defined in this document.
    1.36 +
    1.37 +\subsection{naming}
    1.38 +
    1.39 +Types, methods, functions and variable names should be self-descriptive. 
    1.40 +Avoid using acronyms, expand them, do not hesitate to use long names,
    1.41 +Avoid shortcuts such as \code{sz} for \code{size}. Long names sometimes get in the 
    1.42 +way of being able to read the code:
    1.43 +\begin{verbatim}
    1.44 +for (int loopCount = 0; loopCount < max; loopCount++) 
    1.45 +  {
    1.46 +    // code
    1.47 +  }
    1.48 +\end{verbatim}
    1.49 +loopCount should be renamed to something shorter such as 
    1.50 +\code{i}, \code{j}, \code{k}, \code{l}, \code{m}, and \code{n} 
    1.51 +which are widely used names which identify loop counters:
    1.52 +\begin{verbatim}
    1.53 +for (int i = 0; i < max; i++) 
    1.54 +  {
    1.55 +    // code
    1.56 +  }
    1.57 +\end{verbatim}
    1.58 +Similarly, \code{tmp} is a common way to denote temporary variables. On
    1.59 +the other hand, \code{foo} is not an appropriate name: it says nothing
    1.60 +about the purpose of the variable.
    1.61 +
    1.62 +If you use predicates (that is, functions, variables or methods
    1.63 +which return a single boolean value), prefix the 
    1.64 +name with \code{is} or \code{has}.
    1.65 +
    1.66 +\subsection{Memory management}
    1.67 +
    1.68 +As much as possible, try to pass around objects
    1.69 +by value and allocate them on the stack. If you need to allocate
    1.70 +objects on the heap with new, make sure that the corresponding
    1.71 +call to delete happens where the new took place. i.e., avoid
    1.72 +passing around pointer ownership.
    1.73 +Avoid the use of reference counting and, more generaly, strive to
    1.74 +keep the memory-management model simple.
    1.75 +
    1.76 +\subsection{Templates}
    1.77 +
    1.78 +For now, templates are defined only in the simulator
    1.79 +core and are used everywhere else. Try to keep it that way by 
    1.80 +avoiding defining new templates in model-specific code.
    1.81 +
    1.82  
    1.83  \section{Standards}
    1.84  \subsection{General}
    1.85 @@ -165,10 +221,6 @@
    1.86  digits.  Capital letters are to be used when appropriate between words
    1.87  in a variable name for increased readability.  
    1.88  Variable names should not contain the underscore character.
    1.89 -The variable name should
    1.90 -be descriptive of the use of the variable, excepting for temporary
    1.91 -local variables where the function is obvious from the context (for example
    1.92 -loop index variables are commonly a single letter such as {\tt i}).
    1.93  
    1.94  Examples:
    1.95  
    1.96 @@ -472,15 +524,17 @@
    1.97  \end{tt}
    1.98  
    1.99  \item All header files should have an ``include guard'' to prevent accidental
   1.100 -inclusion of the file multiple times in a single compilation unit.
   1.101 +inclusion of the file multiple times in a single compilation unit. The include
   1.102 +guard should be named after the file name. If the file name is \code{foo-bar.h}, then the
   1.103 +include guard should be named \code{FOO\_BAR\_H}
   1.104  
   1.105  Example:
   1.106  
   1.107  \begin{tt}
   1.108 -\#ifndef \_\_tcp\_h\_\_  \\
   1.109 -\#define \_\_tcp\_h\_\_ \\
   1.110 +\#ifndef FOO\_BAR\_H  \\
   1.111 +\#define FOO\_BAR\_H \\
   1.112  
   1.113 -// (Contents of tcp.h here
   1.114 +// (Contents of foo-bar.h here
   1.115  
   1.116  \#endif
   1.117  \end{tt}