Rather than enumerate the format of every possible line you might write in C++, we'll point out specific aspects of the CHAI 3D coding conventions that might not be considered 'standard' C++ style. And of course, the best reference is the code itself; if you start from an existing CHAI 3D file as a stencil, you'll find it hard _not_ to stick to the conventions.
Whitespace and Indents:
File, Class, Variable, and Function Names:
- All symbols should start new words with a captial letter, e.g. selectedObject
- Class names always begin with a lowercase 'c' followed by a capital letter, e.g. cCamera
- The files that define the class cObject are typically called CObject.h and CObject.cpp (with capital C's)
- Function parameter names begin with a_, followed by a lowercase letter, e.g. a_selectedObject
- Member variable names begin with m_, followed by a lowercase letter, e.g. m_myPrivateVariable
- Local variables and function names begin with a lowercase letter, e.g. selectedObject or getGlobalPos(...)
- Functions that represent callbacks should begin with 'on', e.g. onDisplayReset()
- Global variable names begin with g_, followed by a lowercase letter, e.g. g_myGlobalVariable
Comments:
- Every file that is to be incorporated into CHAI 3D should have the big CHAI 3D header on it, and www.chai3d.org should always be listed as an author... it's at the top of every file, but for completeness I'm pasting it at the end of this file.
- All inline comments (comments you sprinkle in your code, as opposed to function or file header comments) should use C++-type comments... i.e. '//' comments, not '/*' comments. So a multi-line comment should look like this:
// I'm using a lot of words right now
// to tell you that I'm incrementing
// a variable called 'i'...
i++;
- We use doxygen, so we need to mark header comments in the doxygen-ish style. Every function gets one "brief" description and one "long" description... we typically put a brief description before a function declaration (in a header file) and a long description before a function definition (in a .cpp file).
Brief descriptions look like this:
//! Set the local position of this object
inline void setPos(const cVector3d& a_pos) { m_localPos = a_pos; }
...and cannot exceed one line (otherwise doxygen treats them as long descriptions).
Long descriptions look like this:
//===========================================================================
/*!
Create a new vertex and add it to the vertex list.
\fn unsigned int cMesh::newVertex(const double a_x, const double
a_y, const double a_z)
\param a_x X coordinate of vertex.
\param a_y Y coordinate of vertex.
\param a_z Z coordinate of vertex.
\return Return index position of new vertex.
*/
//===========================================================================
unsigned int cMesh::newVertex(const double a_x, const double a_y, const double a_z)
{
...
Note the exclamation point, which tells doxygen that a description is coming. Also note the \fn tag to delimit the function name, the \param tag to delimit parameters, and the \return tag to delimit return values.
- Similarly, each class should have an associated doxygen description wherever it's declared, a la:
//===========================================================================
/*!
\class cCamera
\brief cCamera describes a virtual Camera located inside the world.
Its job in life is to set up the OpenGL projection matrix
for the current OpenGL rendering context...
*/
//===========================================================================
Header Files:
- Don't let inline or one-line functions take up tons of space... i.e., please do this:
//! Set the local position of this object
inline void setPos(const cVector3d& a_pos) { m_localPos = a_pos; }
Not this...
//---------------------------------------
//! Set the local position of this object
//---------------------------------------
inline void setPos(const cVector3d& a_pos)
{
m_localPos = a_pos;
}
Particularly when a lot of these functions come one after another (often set/get functions), doing the latter can make header files really difficult to read.
- Include a blank line between each function in a header file... this makes your headers much more readable. Alternatively, place a blank line after a few closely-related functions to delimit a new category of function.
Coding / Performance Tips:
- Remember to declare functions inline if they hardly do anything (e.g. setPos())
- Remember to declare functions const if they don't modify any member variables
- Remember to take parameters by reference if all you're going to do is copy them (i.e. if they're const), to avoid extra stack copies. This is particularly relevant for complex types being passed as parameters.
- Remember to declare parameters const if you don't need to modify them
- Always set pointers to NULL immediately after you delete them
- Remember to (almost) always declare your destructors virtual
- Any time you change an OpenGL state variable, be nice and put the state back to where it was when you're finished, unless you have a specific reason to do otherwise. Use glGet to get the state beforehand for any state variables you're going to futz with. Similarly, always leave the GL matrix mode set to modelview when you're finished with any matrix strack manipulations you might be doing.
- Avoid using namespace std;, particularly in header files. This makes supporting multiple compilers more difficult, as difficult compilers place different things in different namespaces.
- Avoid using friend and typeid wherever possible; they make extending CHAI more difficult in most cases.
As Promised, The Big CHAI 3D Header Comment to be Included at The Top of Every File:
//===========================================================================
/*
This file is part of the CHAI 3D visualization and haptics libraries.
Copyright (C) 2003-2009 by CHAI 3D. All rights reserved.
This library is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License("GPL") version 2
as published by the Free Software Foundation.
For using the CHAI 3D libraries with software that can not be combined
with the GNU GPL, and for taking advantage of the additional benefits
of our support services, please contact CHAI 3D about acquiring a
Professional Edition License.
\author: <http://www.chai3d.org>
\author: John Lennon
\version 2.0.0
*/
//===========================================================================
|
|