diff --git a/doc/codingstd.txt b/doc/codingstd.txt index 6369035e9..31b5b9d23 100644 --- a/doc/codingstd.txt +++ b/doc/codingstd.txt @@ -1,210 +1,2 @@ - 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 - */ - -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 - */ -#include "my-class.h" - -namespace ns3 { - -MyClass::MyClass () -{} - -... - -} // namespace ns3 - +The project coding style document is maintained at: +http://www.nsnam.org/codingstyle.html diff --git a/doc/contributing.txt b/doc/contributing.txt index 13da6989d..f9a1afdb5 100644 --- a/doc/contributing.txt +++ b/doc/contributing.txt @@ -1,63 +1,7 @@ Contributing to the ns-3 project -------------------------------- -ns-3 is an open source project backed by an NSF CISE CRI grant. -Although the NSF PIs have specific aims to fulfill, we want others to -contribute, and we'd like to have a broad community of users and -developers, with the goal of a self-sustaining project downstream. -The project is currently in a bootstrapping phase, but we welcome -ambitious developers who might want to help shape the early design. - -Despite the lack of a formal contribution process to the ns-3 -project, there are a number of steps which we expect every -potential contributor to follow. These naturally stem from -the open-source roots of the project: - - - first, you should subscribe to the ns-developers - mailing-list (see http://www.nsnam.org/mailing_lists.html) - - - then, you should send an email there stating your interest - in working on a specific part of the models and trying - to explain how you would like to implement it, what - resources you have, etc. - - - you should be prepared to work together with the other - potential contributors who want to work on the same models. - - - you should be prepared to go through code reviews with the - ns-3 development team prior to integration. The goal of these - code reviews is to: - - ensure adherence to the coding style of the project - (see doc/codingstyle.html) - - ensure that the structure of your code has a certain - coherence with regard to the rest of the ns-3 codebase - - improve the quality of the code: we strongly believe in - the old saying: "many eyes make all bugs shallow". - - increase code reuse by trying to generalize certain - useful pieces of your code to make them available to - other models. - - - you should be prepared to try to integrate as many tests - in the codebase as possible: we understand that writing - tests is not sexy and that not everyone is convinced that - they improve the code-writing poductivity which is why - we do not enforce strict rules about testing. However, - we expect model authors to answer basic questions about - how they plan to test and validate their models. - - - you should be prepared to maintain your model once it is - integrated: while we consider every bug filed against the - simulator as being a bug we must deal with and while we - will try to fix as many bugs as humanly possible, we - also expect model authors to act as responsible maintainers - and be reactive to bug reports concerning their models. - - - The project has decided upon GNU GPLv2 as the licensing structure. - All simulation software in the ns-3 repositories will be GNU GPLv2 - or GNU GPLv2-compatible (with non-GPLv2 licensing reserved for - ports of pre-existing code under a different license, such as BSD). - You do not have to assign your copyright to the ns-3 project but - you must accept the terms of the GPLv2 and attest that your - contributions can be licensed under those terms. See the - following link: - http://www.fsf.org/licensing/licenses/info/GPLv2.html +ns-3 is a free, open source software project that welcomes contributions +from users worldwide. Please see the following web page for how to +contribute: +http://www.nsnam.org/contributing.html diff --git a/doc/modules b/doc/modules index b7417e476..c3c419094 100644 --- a/doc/modules +++ b/doc/modules @@ -46,6 +46,7 @@ * * The "internet-stack" module contains: * - an Ipv4 stack + * - an Ipv6 stack * - an ARP module * - a UDP and a TCP implementation *