Rather than enumerate the format of every possible line you might write in C++, I'll try to point out specific aspects of the CHAI 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 file as a stencil, you'll find it hard _not_ to stick to the conventions.
Brief descriptions should look like this:
Long descriptions look like this:
Whitespace and indents
void cGenericObject::onDisplayReset(const bool a_affectChildren)
{
// Forward this call to my children...
// update children
if (a_affectChildren)
{
for (unsigned int i=0; i<m_children.size(); i++)
{
m_children[i]->onDisplayReset(true);
}
}
} // void onDisplayReset(...)
File, class, variable, and function names
Comments
// I'm using a lot of words right now
// to tell you that I'm incrementing
// a variable called 'i'...
i++;
//! 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).//===========================================================================
/*!
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.//===========================================================================
/*!
\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
//! 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.
Coding/Performance tips
As promised, the big CHAI 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-2004 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: Joe Smith
\version 1.1
\date 01/2004
*/
//===========================================================================
Written by Dan Morris, September 2004