Programming conventions

In this section we will define the programming conventions which should be used when programming elements of the PAC-Library. The responsibility that these conventions are enforced lie first of all by the person (or persons) mainly responsible for PAC. However, this will only be successful, if everybody tries to follows these rules.

Supervisors of students which program for PAC are strongly urged to enforce a proper programming style by not accepting any work that does not conform.

This might seem rather strict, however from experience I know that the programming style of 99% of all students (and supervisors) is unreadable. Especially in larger projects this can lead to non-servicable source code, which, in the long run, seals the death warrant for any software project.

When writing software you should always use the Doxygen documenting syntax at least in your header files, to give other users an idea what a particular class is about and, very importantly, what each function of a class does.

Before you start programming you should think about the structure of the programm you want to write, and how you can encapsulate the functionality in separate classes. Each class should have a header file with a .h extension, and an implementation file with a .cpp extension.

The name of class always has to start with a capital C. The filenames for the header and implementation file of this class should omit this leading C. For example, the class CTest is declared in file Test.h and implemented in file Test.cpp.

The header file should look like this:

/** @file CTest.h
	@author John Smith
    @date June 2002
	@brief Implements class CTest
**/

/** @author John Smith
    @date June 2002
	@ingroup testgroup
	@brief This class is just for testing.

    Here follows some detailed description of the class.
**/
class CTest
{
public:
	/** @brief This is a test function.

	    Here we discuss what the function does.
		@param iData Integer data.
		@exception std::out_of_range Thrown if iData is out of range.
		@return true if successful, otherwise false.
	**/
	bool TestFunc(int iData) throw(std::out_of_range);

protected:
	/** Member variables always start with a 'm_'.
	    An integar value. */
	int m_iVal;
	double m_dVal; ///< Here we describe the variable after its declaration.

private:
	/// A static member variable should start with 'sm_'
	static int sm_iCount;
};
\endvabatim

And this is the implementation file:

\verbatim
// Implementation of CTest class.
// @author John Smith.

// Implementation of static member variables.
int CTest::sm_iCount = 0;

/////////////////////////////////////////////////////
// The TestFunc.

bool TestFunc(int iData) throw(std::out_of_range)
{
	int i;

	if (iData > 10)
		throw std::out_of_range();

	// Using m_ for member variables helps us
	// to distinguish them from local variables.
	m_iVal = iData*100;

	for(i = 0; i < 100; i++)
	{
		// Do something...
	}

	return true;
}

In the above examples of Test.h and Test.cpp we have already used the conventions for writing classes, functions, documentation and writing variable names. In the following we will give these conventions again explicitly.

Programming

1. Class names start with a capital C, interface names with a capital I, struct names with a capital S and type names with a capital T.
2. Member variable names always start with a "m_". This helps to distinguish them later from local variables. This can be very useful in complicated functions.
3. Variables in general start with a small letter indicating their type and then carry on with a capital letter. For example, int iVal;. If a variable is a pointer, then an additional p should be placed in front of the variable name. For example, char *pcText. The following letters should be used for the different types:
   • void: v
   • bool: b
   • char: c
   • short: sh
   • int: i
   • unsigned: u
   • long: l
   • float: f
   • double: d
   • string: s
   • vector: vec
   • list: list
   • map: map
   • stream: z

Documentation
In general, it is sufficient to document the header file in Doxygen style. A documentation block for an object is placed before the object. The documentation block should contain at least a brief description of the object (). A following detailed description must be preceded by an empty line.

//Documentation block for classes

/** @author
	@date
	@ingroup
	@brief

	detailed description
*/

The \ingroup command specifies the module your code belongs to. I let \date and \author speak for themselves. Note that C++ style comments like // are ignored by Doxygen.

//Documentation block for member functions

/** @brief
	@param
	@return

	detailed description
*/

Add a \param for each parameter your function accepts. Omit \return if your function is void.
In case you just want to briefly discribe some variables, it is cumbersome to build a whole documentation block. Instead write:

/// Brief description

The documentation block for the file is placed at the very top of the file it belongs to. In fact, it could be written elsewhere, because the keyword \file makes sure to which file it belongs to, but let's keep things simple, ok. The file documentation is missing an \ingroup command, because it is not the file we want to categorize but the objects it contains. Only if the file does not contain classes, but, say, important defines, you may want to add it to a certain module.

//Documentation block for files

/** @file
	@author
    @date
	@brief

	detailed description
**/

Remember: Only good documentation keeps software alive!

Perception-Action Components Library - PACLib developed by the Cognitive Systems Group