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