Coding conventions

From CSP

Table of contents

2.1 General rules
2.2 Header files
2.3 Source files
2.4 Member names
2.5 Namespaces
2.6 Cleanup old code

Documentation

All new code (and existing code, as time permits) must be documented according to the following guidelines. Good documentation is absolutely essential given the scale (both in terms of size and duration) of this project. In fact, good documentation is probably more important than the code itself.

Use Doxygen for source code documentation. Below is a sample Doxygen comment to indicate the preferred style. Note that the brief description (one sentence max) starts on the first line of the comment. If more detail is required, additional paragraphs can be added after the brief description (separated by a blank line in the comment). Doxygen has many special commands, such as @param, that can be used to provide better documentation. See Special Commands (http://www.stack.nl/~dimitri/doxygen/commands.html) for a complete list.

       /** Sets the IP address from a string representation of the 
        *  numeric address, ie "127.0.0.1" 
        * 
        *  @param host The string representation of the IP address 
        *  @return true if successful 
        */ 
       bool setIPAddress(const char *host);

For significant new infrastructure, write internal and external documentation to provide an overview of how groups of classes are meant to interact with each other and with the rest of the project. Both executive summary level and more detailed descriptions are desirable. Examples showing the proper use of the new code are often appropriate. A reasonably concise overview should be placed in a @file comment in one or more of the new source files, using Doxygen tags like @code to mark examples. External documentation should be added to the wiki, and can be much more elaborate than the Doxygen comments. Feel free to add extended example or figures to the wiki page to illustrate the key points.

[edit]

Coding style

Here are the "official" coding guidelines for CSP. Not all of the existing code complies with these (or any single set of) guidelines. To the extent possible, try to do a little clean-up here and there whenever you are working with existing code to improve the overall consistency.

[edit]

General rules

Indent with tabs. Please do this religously (turn on visible tabs if your editor supports it). Especially important: never mix tabs and spaces when indenting Python code. When aligning wrapped lines in C++, use the same tab indentation as the first line, followed by spaces for alignment.
Classes are MixedCaseLikeThis
Methods are mixedCaseLikeThis
Member names: see below
Classes should define a default constructor (not inline)
Classes with virtual methods must define a virtual destructor (often empty)
Classes should start with a doxygen comment of the form:

 /** brief class description (one line only) 
  *  
  *  longer description (if appropriate/available) 
  */

[edit]

Header files

Minimize header dependencies; use forward declarations whenever possible.
Layout:

1. Copyright notice
2. Doxygen @file comment
3. #ifdef/#define __FILENAMEINALLCAPS_H__
4. #include ...
5. externs, class declarations, etc.
6. #endif // __FILENAMEINALLCAPS_H__
7. blank line

For example:

 // Combat Simulator Project - FlightSim Demo 
 // Copyright (C) 2004 The Combat Simulator Project 
 // http://csp.sourceforge.net 
 //  
 // This program is free software; you can redistribute it and/or 
 // modify it under the terms of the GNU General Public License 
 // as published by the Free Software Foundation; either version 2 
 // of the License, or (at your option) any later version. 
 //  
 // This program is distributed in the hope that it will be useful, 
 // but WITHOUT ANY WARRANTY; without even the implied warranty of 
 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
 // GNU General Public License for more details. 
 //  
 // You should have received a copy of the GNU General Public License 
 // along with this program; if not, write to the Free Software 
 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA. 
 
 
 /** 
  * @file SystemsModel.h 
  * 
  * @brief Vehicle systems base classes and infrastructure. 
  * 
  **/ 
 
 #ifndef __SYSTEMSMODEL_H__ 
 #define __SYSTEMSMODEL_H__ 
 
 #include <System.h> 
 #include <PhysicsModel.h> 
 #include <Controller.h> 
 
 /** Base class for detailed vehicle models. 
  * 
  *  Systems model instances serve as the root node of System trees.   
  *  The model defines a data bus shared by all systems it contains,  
  *  and serves as the external interface of the composite system. 
  */ 
 class SystemsModel: public System { 
 ... 
 }; 
  
 #endif // __SYSTEMSMODEL_H__

[edit]

Source files

Start with copyright notice.
Include the corresponding header first (e.g. the first header included in Foo.cpp should be Foo.h).
End with a blank line.

[edit]

Member names

Variable names should be of the form m_CapitalWords.
Don't kill yourself trying to convert existing code to this convention. Just try to stick to it for new code. When adding variables to existing code it's better to be consistent than to follow this rule religiously.

[edit]

Namespaces

Don't do 'using namespace std;' (especially in headers!)
Do 'using std::string;' or, better, use the qualified names directly.
See Identifiers To Avoid in C++ Programs (http://oakroadsystems.com/tech/cppredef.htm) for details.
Most code lives inside the csp namespace. Use the CSP_NAMESPACE_BEGIN and CSP_NAMESPACE_END macros to declare code within this namespace.

[edit]

Cleanup old code

If you are feeling like a good Samaratin, you are welcome to clean up old code to be more consistent with these guidelines.
Removing trailing spaces and keeping the copyright notices up to date is always appreciated.

[edit]