doc/codingstd.txt
author Tom Henderson <tomh@tomh.org>
Fri, 18 May 2007 10:27:42 -0700
changeset 657 be551a3b07c6
permissions -rw-r--r--
minor changes due to documentation review
tomh@657
     1
       The Ns-3 Coding Style
tomh@657
     2
tomh@657
     3
/*
tomh@657
     4
 * Note:  This file is incomplete and will be converted to non-text (html,pdf)
tomh@657
     5
 * formats at a future date
tomh@657
     6
 */
tomh@657
     7
tomh@657
     8
1) Code layout
tomh@657
     9
     -----------
tomh@657
    10
tomh@657
    11
The code layout follows the GNU coding standard layout for C and extends
tomh@657
    12
it to C++. Do not use tabs for indentation. Indentation spacing is 2
tomh@657
    13
spaces as outlined below:
tomh@657
    14
tomh@657
    15
void 
tomh@657
    16
Foo (void)
tomh@657
    17
{
tomh@657
    18
  if (test)
tomh@657
    19
    {
tomh@657
    20
      // do stuff here
tomh@657
    21
    }
tomh@657
    22
  else
tomh@657
    23
    {
tomh@657
    24
      // do other stuff here
tomh@657
    25
    }
tomh@657
    26
tomh@657
    27
  for (int i = 0; i < 100; i++)
tomh@657
    28
    {
tomh@657
    29
      // do loop
tomh@657
    30
    }
tomh@657
    31
tomh@657
    32
  while (test)
tomh@657
    33
    {
tomh@657
    34
      // do while
tomh@657
    35
    }
tomh@657
    36
tomh@657
    37
  do
tomh@657
    38
    {
tomh@657
    39
      // do stuff
tomh@657
    40
    } while ();
tomh@657
    41
}
tomh@657
    42
tomh@657
    43
The following is not recommended:
tomh@657
    44
tomh@657
    45
if (test) statement
tomh@657
    46
tomh@657
    47
if (test)
tomh@657
    48
  statement
tomh@657
    49
tomh@657
    50
for (...) statement
tomh@657
    51
tomh@657
    52
Each statement should be put on a separate line to increase readability.
tomh@657
    53
Short one-line comments can use the C++ comment style, that is, '//'
tomh@657
    54
but longer comments should use C-style comments:
tomh@657
    55
/*
tomh@657
    56
 *
tomh@657
    57
 *
tomh@657
    58
 */
tomh@657
    59
tomh@657
    60
tomh@657
    61
2) Naming Patterns
tomh@657
    62
   ---------------
tomh@657
    63
tomh@657
    64
2.1) Name encoding
tomh@657
    65
     -------------
tomh@657
    66
Function, Method, and Type names should follow the CamelCase convention:
tomh@657
    67
words are joined without spaces and are capitalized. For example,
tomh@657
    68
"my computer" is transformed into MyComputer. Do not use all capital 
tomh@657
    69
letters such as MAC or, PHY, but choose instead Mac or Phy. Do not use
tomh@657
    70
all capital letters, even for acronyms such as EDCA: use Edca instead.
tomh@657
    71
The goal of the CamelCase convention is to ensure that the words which
tomh@657
    72
make up a name can be separated by the eye: the initial Caps fills
tomh@657
    73
that role.
tomh@657
    74
tomh@657
    75
Variable names should follow a slight variation on the base CamelCase
tomh@657
    76
convention: camelBack. For example, the variable "user name" would be
tomh@657
    77
named "userName". This variation on the basic naming pattern is used to
tomh@657
    78
allow a reader to distinguish a variable name from its type. For example,
tomh@657
    79
"UserName userName;" would be used to declare a variable named userName
tomh@657
    80
of type UserName.
tomh@657
    81
tomh@657
    82
Global variables should be prefixed with a "g_" and member variables
tomh@657
    83
(including static member variables) should be prefixed with a "m_". The
tomh@657
    84
goal of that prefix is to give a reader a sense of where a variable of
tomh@657
    85
a given name is declared to allow the reader to locate the variable 
tomh@657
    86
declaration and infer the variable type from that declaration. For example
tomh@657
    87
you could declare in your class header my-class.h:
tomh@657
    88
tomh@657
    89
class MyClass
tomh@657
    90
{
tomh@657
    91
  void MyMethod (int aVar);
tomh@657
    92
  int m_aVar;
tomh@657
    93
  static int m_anotherVar;
tomh@657
    94
};
tomh@657
    95
tomh@657
    96
and implement in your class file my-class.cc:
tomh@657
    97
tomh@657
    98
int MyClass::m_anotherVar = 10;
tomh@657
    99
static int g_aStaticVar = 100;
tomh@657
   100
int g_aGlobalVar = 1000;
tomh@657
   101
tomh@657
   102
void
tomh@657
   103
MyClass::MyMethod (int aVar)
tomh@657
   104
{
tomh@657
   105
  m_aVar = aVar;
tomh@657
   106
}
tomh@657
   107
tomh@657
   108
2.2) Choosing names
tomh@657
   109
tomh@657
   110
Variable, function, method, and type names should be based on the
tomh@657
   111
english language. Furthermore, always try to choose descriptive
tomh@657
   112
names for them. Types are often english names such as: Packet, 
tomh@657
   113
Buffer, Mac, or Phy. Functions and Methods are often named
tomh@657
   114
based on verbs and adjectives: GetX, DoDispose, ClearArray, etc.
tomh@657
   115
tomh@657
   116
A long descriptive name which requires a lot of typing is always
tomh@657
   117
better than a short name which is hard to decipher. Do not use
tomh@657
   118
abbreviations in names unless the abbreviation is really unambiguous
tomh@657
   119
and obvious to everyone. Do not use short inapropriate names such
tomh@657
   120
as foo, bar, or baz. The name of an item should always match its 
tomh@657
   121
purpose. As such, names such as tmp to identify a temporary
tomh@657
   122
variable or such as 'i' to identify a loop index are ok.
tomh@657
   123
tomh@657
   124
3) File layout and code organization
tomh@657
   125
   ---------------------------------
tomh@657
   126
tomh@657
   127
A class named MyClass should be declared in a header named my-class.h
tomh@657
   128
and implemented in a source file named my-class.cc. The goal of this
tomh@657
   129
naming pattern is to allow a reader to quickly navigate through
tomh@657
   130
the ns-3 codebase to locate the source file relevant to a specific
tomh@657
   131
type.
tomh@657
   132
tomh@657
   133
Each my-class.h header should start with the following comments: the
tomh@657
   134
first line ensures that developers who use the emacs editor will be 
tomh@657
   135
able to indent your code correctly. The following lines ensure that
tomh@657
   136
your code is licensed under the GPL, that the copyright holders
tomh@657
   137
are properly identified (typically, you or your employer), and
tomh@657
   138
that the actual author of the code is identified. The latter is
tomh@657
   139
purely informational and we use it to try to track the most
tomh@657
   140
appropriate person to review a patch or fix a bug.
tomh@657
   141
tomh@657
   142
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
tomh@657
   143
/*
tomh@657
   144
 * Copyright (c) YEAR COPYRIGHTHOLDER
tomh@657
   145
 * 
tomh@657
   146
 * 3-paragran GPL blurb
tomh@657
   147
 *
tomh@657
   148
 * Author: MyName <myemail@foo.com>
tomh@657
   149
 */
tomh@657
   150
tomh@657
   151
Below these C-style comments, always include the following which
tomh@657
   152
defines a set of header guards (MY_CLASS_H) used to avoid multiple
tomh@657
   153
header includes, which ensures that your code is included
tomh@657
   154
in the "ns3" namespace and which provides a set of doxygen comments
tomh@657
   155
for the public part of your class API. Detailed information
tomh@657
   156
on the set of tags available for doxygen documentation is described
tomh@657
   157
in the doxygen website: http://www.doxygen.org.
tomh@657
   158
tomh@657
   159
#ifndef MY_CLASS_H
tomh@657
   160
#define MY_CLASS_H
tomh@657
   161
tomh@657
   162
namespace n3 {
tomh@657
   163
tomh@657
   164
/**
tomh@657
   165
 * \brief short one-line description of the purpose of your class
tomh@657
   166
 *
tomh@657
   167
 * A longer description of the purpose of your class after a blank
tomh@657
   168
 * empty line.
tomh@657
   169
 */
tomh@657
   170
class MyClass
tomh@657
   171
{
tomh@657
   172
public:
tomh@657
   173
 MyClass ();
tomh@657
   174
 /**
tomh@657
   175
  * \param firstParam a short description of the purpose of this parameter
tomh@657
   176
  * \returns a short description of what is returned from this function.
tomh@657
   177
  *
tomh@657
   178
  * A detailed description of the purpose of the method.
tomh@657
   179
  */
tomh@657
   180
 int DoFoo (int firstParam);
tomh@657
   181
private:
tomh@657
   182
 void MyPrivateMethod (void);
tomh@657
   183
 int m_myPrivateMemberVariable;
tomh@657
   184
};
tomh@657
   185
tomh@657
   186
} // namespace ns3
tomh@657
   187
tomh@657
   188
#endif /* MY_CLASS_H */
tomh@657
   189
tomh@657
   190
The my-class.cc file is structured similarly:
tomh@657
   191
tomh@657
   192
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
tomh@657
   193
/*
tomh@657
   194
 * Copyright (c) YEAR COPYRIGHTHOLDER
tomh@657
   195
 * 
tomh@657
   196
 * 3-paragran GPL blurb
tomh@657
   197
 *
tomh@657
   198
 * Author: MyName <myemail@foo.com>
tomh@657
   199
 */
tomh@657
   200
#include "my-class.h"
tomh@657
   201
tomh@657
   202
namespace ns3 {
tomh@657
   203
tomh@657
   204
MyClass::MyClass ()
tomh@657
   205
{}
tomh@657
   206
tomh@657
   207
...
tomh@657
   208
tomh@657
   209
} // namespace ns3
tomh@657
   210