The Ns-3 Coding Style

/*

 * Note:  This file is incomplete and will be converted to non-text (html,pdf)

 * formats at a future date

 */

1) Code layout

     -----------

The code layout follows the GNU coding standard layout for C and extends

it to C++. Do not use tabs for indentation. Indentation spacing is 2

spaces as outlined below:

void 

Foo (void)

{

  if (test)

    {

      // do stuff here

    }

  else

    {

      // do other stuff here

    }

  for (int i = 0; i < 100; i++)

    {

      // do loop

    }

  while (test)

    {

      // do while

    }

  do

    {

      // do stuff

    } while ();

}

The following is not recommended:

if (test) statement

if (test)

  statement

for (...) statement

Each statement should be put on a separate line to increase readability.

Short one-line comments can use the C++ comment style, that is, '//'

but longer comments should use C-style comments:

/*

 *

 *

 */

2) Naming Patterns

   ---------------

2.1) Name encoding

     -------------

Function, Method, and Type names should follow the CamelCase convention:

words are joined without spaces and are capitalized. For example,

"my computer" is transformed into MyComputer. Do not use all capital 

letters such as MAC or, PHY, but choose instead Mac or Phy. Do not use

all capital letters, even for acronyms such as EDCA: use Edca instead.

The goal of the CamelCase convention is to ensure that the words which

make up a name can be separated by the eye: the initial Caps fills

that role.

Variable names should follow a slight variation on the base CamelCase

convention: camelBack. For example, the variable "user name" would be

named "userName". This variation on the basic naming pattern is used to

allow a reader to distinguish a variable name from its type. For example,

"UserName userName;" would be used to declare a variable named userName

of type UserName.

Global variables should be prefixed with a "g_" and member variables

(including static member variables) should be prefixed with a "m_". The

goal of that prefix is to give a reader a sense of where a variable of

a given name is declared to allow the reader to locate the variable 

declaration and infer the variable type from that declaration. For example

you could declare in your class header my-class.h:

class MyClass

{

  void MyMethod (int aVar);

  int m_aVar;

  static int m_anotherVar;

};

and implement in your class file my-class.cc:

int MyClass::m_anotherVar = 10;

static int g_aStaticVar = 100;

int g_aGlobalVar = 1000;

void

MyClass::MyMethod (int aVar)

{

  m_aVar = aVar;

}

2.2) Choosing names

Variable, function, method, and type names should be based on the

english language. Furthermore, always try to choose descriptive

names for them. Types are often english names such as: Packet, 

Buffer, Mac, or Phy. Functions and Methods are often named

based on verbs and adjectives: GetX, DoDispose, ClearArray, etc.

A long descriptive name which requires a lot of typing is always

better than a short name which is hard to decipher. Do not use

abbreviations in names unless the abbreviation is really unambiguous

and obvious to everyone. Do not use short inapropriate names such

as foo, bar, or baz. The name of an item should always match its 

purpose. As such, names such as tmp to identify a temporary

variable or such as 'i' to identify a loop index are ok.

3) File layout and code organization

   ---------------------------------

A class named MyClass should be declared in a header named my-class.h

and implemented in a source file named my-class.cc. The goal of this

naming pattern is to allow a reader to quickly navigate through

the ns-3 codebase to locate the source file relevant to a specific

type.

Each my-class.h header should start with the following comments: the

first line ensures that developers who use the emacs editor will be 

able to indent your code correctly. The following lines ensure that

your code is licensed under the GPL, that the copyright holders

are properly identified (typically, you or your employer), and

that the actual author of the code is identified. The latter is

purely informational and we use it to try to track the most

appropriate person to review a patch or fix a bug.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

/*

 * Copyright (c) YEAR COPYRIGHTHOLDER

 * 

 * 3-paragran GPL blurb

 *

 * Author: MyName <myemail@foo.com>

 */

Below these C-style comments, always include the following which

defines a set of header guards (MY_CLASS_H) used to avoid multiple

header includes, which ensures that your code is included

in the "ns3" namespace and which provides a set of doxygen comments

for the public part of your class API. Detailed information

on the set of tags available for doxygen documentation is described

in the doxygen website: http://www.doxygen.org.

#ifndef MY_CLASS_H

#define MY_CLASS_H

namespace n3 {

/**

 * \brief short one-line description of the purpose of your class

 *

 * A longer description of the purpose of your class after a blank

 * empty line.

 */

class MyClass

{

public:

 MyClass ();

 /**

  * \param firstParam a short description of the purpose of this parameter

  * \returns a short description of what is returned from this function.

  *

  * A detailed description of the purpose of the method.

  */

 int DoFoo (int firstParam);

private:

 void MyPrivateMethod (void);

 int m_myPrivateMemberVariable;

};

} // namespace ns3

#endif /* MY_CLASS_H */

The my-class.cc file is structured similarly:

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

/*

 * Copyright (c) YEAR COPYRIGHTHOLDER

 * 

 * 3-paragran GPL blurb

 *

 * Author: MyName <myemail@foo.com>

 */

#include "my-class.h"

namespace ns3 {

MyClass::MyClass ()

{}

...

} // namespace ns3