doc/codingstd.txt
changeset 657 be551a3b07c6
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/codingstd.txt	Fri May 18 10:27:42 2007 -0700
     1.3 @@ -0,0 +1,210 @@
     1.4 +       The Ns-3 Coding Style
     1.5 +
     1.6 +/*
     1.7 + * Note:  This file is incomplete and will be converted to non-text (html,pdf)
     1.8 + * formats at a future date
     1.9 + */
    1.10 +
    1.11 +1) Code layout
    1.12 +     -----------
    1.13 +
    1.14 +The code layout follows the GNU coding standard layout for C and extends
    1.15 +it to C++. Do not use tabs for indentation. Indentation spacing is 2
    1.16 +spaces as outlined below:
    1.17 +
    1.18 +void 
    1.19 +Foo (void)
    1.20 +{
    1.21 +  if (test)
    1.22 +    {
    1.23 +      // do stuff here
    1.24 +    }
    1.25 +  else
    1.26 +    {
    1.27 +      // do other stuff here
    1.28 +    }
    1.29 +
    1.30 +  for (int i = 0; i < 100; i++)
    1.31 +    {
    1.32 +      // do loop
    1.33 +    }
    1.34 +
    1.35 +  while (test)
    1.36 +    {
    1.37 +      // do while
    1.38 +    }
    1.39 +
    1.40 +  do
    1.41 +    {
    1.42 +      // do stuff
    1.43 +    } while ();
    1.44 +}
    1.45 +
    1.46 +The following is not recommended:
    1.47 +
    1.48 +if (test) statement
    1.49 +
    1.50 +if (test)
    1.51 +  statement
    1.52 +
    1.53 +for (...) statement
    1.54 +
    1.55 +Each statement should be put on a separate line to increase readability.
    1.56 +Short one-line comments can use the C++ comment style, that is, '//'
    1.57 +but longer comments should use C-style comments:
    1.58 +/*
    1.59 + *
    1.60 + *
    1.61 + */
    1.62 +
    1.63 +
    1.64 +2) Naming Patterns
    1.65 +   ---------------
    1.66 +
    1.67 +2.1) Name encoding
    1.68 +     -------------
    1.69 +Function, Method, and Type names should follow the CamelCase convention:
    1.70 +words are joined without spaces and are capitalized. For example,
    1.71 +"my computer" is transformed into MyComputer. Do not use all capital 
    1.72 +letters such as MAC or, PHY, but choose instead Mac or Phy. Do not use
    1.73 +all capital letters, even for acronyms such as EDCA: use Edca instead.
    1.74 +The goal of the CamelCase convention is to ensure that the words which
    1.75 +make up a name can be separated by the eye: the initial Caps fills
    1.76 +that role.
    1.77 +
    1.78 +Variable names should follow a slight variation on the base CamelCase
    1.79 +convention: camelBack. For example, the variable "user name" would be
    1.80 +named "userName". This variation on the basic naming pattern is used to
    1.81 +allow a reader to distinguish a variable name from its type. For example,
    1.82 +"UserName userName;" would be used to declare a variable named userName
    1.83 +of type UserName.
    1.84 +
    1.85 +Global variables should be prefixed with a "g_" and member variables
    1.86 +(including static member variables) should be prefixed with a "m_". The
    1.87 +goal of that prefix is to give a reader a sense of where a variable of
    1.88 +a given name is declared to allow the reader to locate the variable 
    1.89 +declaration and infer the variable type from that declaration. For example
    1.90 +you could declare in your class header my-class.h:
    1.91 +
    1.92 +class MyClass
    1.93 +{
    1.94 +  void MyMethod (int aVar);
    1.95 +  int m_aVar;
    1.96 +  static int m_anotherVar;
    1.97 +};
    1.98 +
    1.99 +and implement in your class file my-class.cc:
   1.100 +
   1.101 +int MyClass::m_anotherVar = 10;
   1.102 +static int g_aStaticVar = 100;
   1.103 +int g_aGlobalVar = 1000;
   1.104 +
   1.105 +void
   1.106 +MyClass::MyMethod (int aVar)
   1.107 +{
   1.108 +  m_aVar = aVar;
   1.109 +}
   1.110 +
   1.111 +2.2) Choosing names
   1.112 +
   1.113 +Variable, function, method, and type names should be based on the
   1.114 +english language. Furthermore, always try to choose descriptive
   1.115 +names for them. Types are often english names such as: Packet, 
   1.116 +Buffer, Mac, or Phy. Functions and Methods are often named
   1.117 +based on verbs and adjectives: GetX, DoDispose, ClearArray, etc.
   1.118 +
   1.119 +A long descriptive name which requires a lot of typing is always
   1.120 +better than a short name which is hard to decipher. Do not use
   1.121 +abbreviations in names unless the abbreviation is really unambiguous
   1.122 +and obvious to everyone. Do not use short inapropriate names such
   1.123 +as foo, bar, or baz. The name of an item should always match its 
   1.124 +purpose. As such, names such as tmp to identify a temporary
   1.125 +variable or such as 'i' to identify a loop index are ok.
   1.126 +
   1.127 +3) File layout and code organization
   1.128 +   ---------------------------------
   1.129 +
   1.130 +A class named MyClass should be declared in a header named my-class.h
   1.131 +and implemented in a source file named my-class.cc. The goal of this
   1.132 +naming pattern is to allow a reader to quickly navigate through
   1.133 +the ns-3 codebase to locate the source file relevant to a specific
   1.134 +type.
   1.135 +
   1.136 +Each my-class.h header should start with the following comments: the
   1.137 +first line ensures that developers who use the emacs editor will be 
   1.138 +able to indent your code correctly. The following lines ensure that
   1.139 +your code is licensed under the GPL, that the copyright holders
   1.140 +are properly identified (typically, you or your employer), and
   1.141 +that the actual author of the code is identified. The latter is
   1.142 +purely informational and we use it to try to track the most
   1.143 +appropriate person to review a patch or fix a bug.
   1.144 +
   1.145 +/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
   1.146 +/*
   1.147 + * Copyright (c) YEAR COPYRIGHTHOLDER
   1.148 + * 
   1.149 + * 3-paragran GPL blurb
   1.150 + *
   1.151 + * Author: MyName <myemail@foo.com>
   1.152 + */
   1.153 +
   1.154 +Below these C-style comments, always include the following which
   1.155 +defines a set of header guards (MY_CLASS_H) used to avoid multiple
   1.156 +header includes, which ensures that your code is included
   1.157 +in the "ns3" namespace and which provides a set of doxygen comments
   1.158 +for the public part of your class API. Detailed information
   1.159 +on the set of tags available for doxygen documentation is described
   1.160 +in the doxygen website: http://www.doxygen.org.
   1.161 +
   1.162 +#ifndef MY_CLASS_H
   1.163 +#define MY_CLASS_H
   1.164 +
   1.165 +namespace n3 {
   1.166 +
   1.167 +/**
   1.168 + * \brief short one-line description of the purpose of your class
   1.169 + *
   1.170 + * A longer description of the purpose of your class after a blank
   1.171 + * empty line.
   1.172 + */
   1.173 +class MyClass
   1.174 +{
   1.175 +public:
   1.176 + MyClass ();
   1.177 + /**
   1.178 +  * \param firstParam a short description of the purpose of this parameter
   1.179 +  * \returns a short description of what is returned from this function.
   1.180 +  *
   1.181 +  * A detailed description of the purpose of the method.
   1.182 +  */
   1.183 + int DoFoo (int firstParam);
   1.184 +private:
   1.185 + void MyPrivateMethod (void);
   1.186 + int m_myPrivateMemberVariable;
   1.187 +};
   1.188 +
   1.189 +} // namespace ns3
   1.190 +
   1.191 +#endif /* MY_CLASS_H */
   1.192 +
   1.193 +The my-class.cc file is structured similarly:
   1.194 +
   1.195 +/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
   1.196 +/*
   1.197 + * Copyright (c) YEAR COPYRIGHTHOLDER
   1.198 + * 
   1.199 + * 3-paragran GPL blurb
   1.200 + *
   1.201 + * Author: MyName <myemail@foo.com>
   1.202 + */
   1.203 +#include "my-class.h"
   1.204 +
   1.205 +namespace ns3 {
   1.206 +
   1.207 +MyClass::MyClass ()
   1.208 +{}
   1.209 +
   1.210 +...
   1.211 +
   1.212 +} // namespace ns3
   1.213 +