Resources

Topics

RobWorkProject
Code guide lines

Performs the first test void test1();

Introduction

This section will present the coding guidelines that are used in RobWork.

We use the following guide lines:
http://geosoft.no/development/cppstyle.html

With the following exceptions:

In-depth explanations:

a) Naming of source files:

Source files are named in UpperCamelCase (Java style) the following suffixes should be used:
C++ header files: .hpp
C++ source files: .cpp

As a rule of thumb: There should be one .hpp and one .cpp file for each class. The .hpp and .cpp file should have the same name as the class

b) Include guards

Use the following includeguards:

1 #ifndef RW_PACKAGENAME_CLASSNAME_HPP
2 #define RW_PACKAGENAME_CLASSNAME_HPP
3 //...
4 #endif // RW_PACKAGENAME_CLASSNAME_HPP

example:

#ifndef RW_VWORKCELL_SERIALDEVICE_HPP
#define RW_VWORKCELL_SERIALDEVICE_HPP
#endif // RW_VWORKCELL_SERIALDEVICE_HPP

# c) Use of namespaces #

namespace rw{
namespace packagename{
}
}

do not use: "using namespace" in .hpp files. This violates the principle of namespaces "using namespace" must only be used in .cpp files.

d) Class definitions

place public members before protected members, place protected members before private members

class SerialDevice{
public:
...
protected:
...
private:
...
};

e) Documentation

We use doxygen for documentations, doxygen tags should start with a "\@" (JavaDoc style). Brief member descriptions should be prefixed by @brief

We use the same writing style as used in the Java API (see http://java.sun.com/j2se/1.5.0/docs/api/)

Example of good brief member descriptions:
@brief Removes all of the elements of this collection
@brief Constructs an ActionEvent object
@brief Returns a parameter string identifying this action event

Example of bad brief member descriptions:
@brief This method is used for finding the square root

There should be a space between class members and the next documentation block

Right:

class Test{
public:
// //Performs the second test
void test2();
};

Wrong:

class Test{
public:
//Performs the first test
void test1();
//Performs the second test
void test2();
};

f) Indentation

We use indentation level 4

g) Notation for math

When possible use the following notation for code and documentation:

Documentation doxygen code description
$\abx{a}{b}{\bf{T}}$ \f$\abx{a}{b}{\bf{T}}\f$ aTb Transform a to b (or b wrt. a)
$\bf{x}$ \f$\b{x}\f$ X Pose
$\bf{d}$ \bf{d} d Vector
$\hat{\bf{k}}\theta$ \f$\hat{\bf{k}}\theta\f$ k EAA, equivalent angle and axis
$\bf{\nu}$ \bf{\nu} V VelocityScrew
$\bf{v}$ \bf{v} v Linear velocity
$\bf{\omega}$ \bf{\omega} w Angular velocity
$\bf{q}$ \f$\bf{q}\f$ q Joint configuration

h) Include files

.hpp files should be included in the follwing order:

  1. (for .cpp files only) ClassName.hpp
  2. .hpp files from same namespace
  3. RobWork .hpp files
  4. ext includes
  5. other includes
  6. boost includes
  7. stl includes

Example.: (SerialDevice.cpp)

#include "SerialDevice.hpp"
#include "Joint.hpp"
#include "math/Vector.hpp"
#include <stdlib.h>

For source files in test, example and demo use the above rules but include the RobWork files as library files instead of local files (use <file.hpp> instead of "file.hpp")

i) Try to reduce .hpp dependencies

Try to reduce .hpp dependencies by not including more .hpp files than absolutely necessary. Use forward declarations when possible

j) Use tests

Do not remove or comment-out tests from the test directory Write tests

k) Use the RobWork smart pointer

All classes which are expected to be passed as pointers should declare a pointer typedef using the RobWork smart pointer rw::common::Ptr.

1 class MyClass;
2 
3 // A pointer to a MyClass
4 typedef rw::common::Ptr<MyClass> MyClassPtr;

Classes taking pointers to objects should likewise use the smart pointer to determine ownership and avoid memory leaks.

Commit guidelines:

Before you commit:
make (verify that there is no build errors)
make test (verify that there is no build errors and that the changes does not break any of the unit tests)
doxygen (verify that there is no doxygen warnings)
If you added any files make sure that you have made subversion aware of them with "svn add path/to/file"
Verify that example, demo and RobWorkStudio still compiles

When you commit:
Always specify a commit message stating what was changed (this makes it possible for other people to see why you have changes and, more importantly, why you changed it)

Right:

svn commit -m "fixed bug in SerialDevice causing a crash when there was only one frame in the serial chain"

Wrong:

svn commit -m ""