MCA2 Programmer's Guide
Prev	Fast Backward		Fast Forward	Next

Chapter 6. MCA coding standards

Table of Contents

6.1.1. Classes
6.1.2. File names
6.1.3. Variables
6.1.4. Functions
6.1.5. Type Declarations
6.1.6. Constants and enumerations

6.2.1. Class layout
6.2.2. Comments
6.2.3. Accessing instance variables
6.2.4. Initializing instance variables in the class constructor
6.2.5. #define
6.2.6. Sense() and Control()

MCA is the product of many people. Because of this, you will find a lot of different coding styles in the various classes. However, this makes maintaining the framework more difficult and also hinders new users at learning how to use MCA properly. To improve this situation in the future, this chapter provides a coding standard that has been developed in order to have some uniformity in newly written MCA code. Unfortunately, much of the older parts have not been ported completely to this standard, so don't be surprised when you look into the source and find inconsistencies. In any case, you should try to follow the guidelines detailed below. In the long run, it makes life easier for all.

6.1. Naming Conventions

This sections describes how to name things in MCA2. A few general rules apply to all names:

Every name must be an english expression. Don´t use other languages or even mix them.
Don't abbreviate words. This is often unnecessary as most editors have the possibility of auto-appending possible endings and the code is less readable.

6.1.1. Classes

When creating a new module, group, part or plain class, choose a name that describes the function of this class well, rather than describing whether it is a module, group or part. Capitalize each word contained in the name and do not use special separating characters like underscores. Prepend a single lowercase letter to the name according to the class type:

Prepend a 'p' to all parts.
Prepend a 'g' to all groups.
Prepend a 'm' to all modules.
Prepend a 't' to all general classes that are no parts/groups/modules.
Prepend a 's' to all purely static classes (containing utility functions etc.).

Example 6-1. Some acceptable class names.

Parts: pTestInertialSystem, pHardwareAbstraction, pControlPanTiltUnit

Groups: gStereoVision, gControlLeg, gDetectHumans

Modules: mAddOne, mReflectSensorValues, mMotionFSM

General classes: tTopologicalMap, tGraphElement

Static classes: sVisionBlackboardUtils, sTextureUtils

6.1.1.1. Scripts for generating new classes

It is recommended to use one of the supplied scripts to generate template class files (.C and .h files) for you with the correct first letter. The following scripts exist for this purpose in the /scripts subdir of MCA:

newPart base_path name: Creates a new part. The .C file is created with the given name in the $MCAHOME/base_path/src subdirectory. A 'p' is automatically prepended. No header file is generated.
newGroup base_path name: Creates a new group. Parameters are evalulated like in the newPart script. A 'g' is automatically prepended to the given name. Additional to the .C file, a header file is created in $MCAHOME/base_path/include.
newModule base_path name: Creates a new module. A 'm' is automatically prepended to the given name. Both .C and .h files are created.
newClass base_path name: Creates a new class. A 't' is automatically prepended to the given name. Both .C and .h files are created.
newStaticClass base_path name: Creates a new static class. A 's' is automatically prepended to the given name. Both .C and .h files are created.

6.1.2. File names

When you do not use the provided scripts and want to create new class files on your own, create two files for each class: A source and a header file. For parts, the header file is optional.

Avoid declaring more than one class in the same file. Sole exceptions of this rule should be nested classes and container classes exclusively used by the companion class.

Name all files exactly like the class they contain, including the leading p,g,m,t or s.

6.1.3. Variables

Variables may consist of phrases, but never contain capitals. Words are separated by underscores.

Example 6-2. Examples for variable definitions.

int this_is_a_integer_variable;
float distance_to_obstacle;
bool activated;

6.1.4. Functions

In function names, words are separated using capitals without underscores. Even the first letter must be a capital. The parameters of a function and of course the internal variables must conform to the coding standards for variables.

Example 6-3. Examples for function definitions.

inline bool IsActivated() { return activated; }
inline float DistanceToObstacle(tDriveMethod drive_method);

6.1.5. Type Declarations

Type names are just like funktion names but contain a leading small t.

Example 6-4. Examples for type declarations.

typedef char* tDescription;
typedef unsigned char tThisIsAByteDeclaration;

6.1.6. Constants and enumerations

Constants start with a lowercase c, enumerations with a lowercase e. The constant or enumeration name itself can be formatted in two ways:

Completely capitalized and separated by underscores.
Like a function name, each word starting with a capitalized letter and not separated by underscores.

In both cases, a prefix containing type information and ending with a underscore is acceptable.

Example 6-5. Defining constants and enumerations

const int cCONSTANT_INT;
const float cPredefinedFloat;

enum tParameterType {ePT_BOOL,ePT_INT,ePT_FLOAT,ePT_SRING};
enum tExceptionType
{
  eET_ParameterChanged,
  eET_PrepareForFirstSense,
  eET_PrepareForFirstControl,
  eET_PrepareForBreak,
  eET_PrepareForRestart,
};

enum {eERROR,eSTART,eSTOP};

Prev	Home	Next
Accessing blackboard content without locking		Coding guidelines