Coding style & tools

Hello,

I'd like to start a thread about coding style and coding tools.  I know some 
may find this early, but it's better that we decide this before the very 
first pieces of code are written.

This is what I _propose_ :

Indentation : 
with spaces of width 3.  No tabs.  Tabs have the advantage that anyone can 
use his/her own indentation width but since everyone uses spaces from time to 
time after/in/before the tabs, the result can be very messy

Class Names : 
 - Start with a capital, every word after the first word is also capital.  
 - Next, when inheritance is used, the classname of the sub class is the 
classname of the super (base) class, followed by an additional string
 - The class name only expresses the "is-a" relation and not the "has a" 
properties unless to differentiate between to derived classes on the same 
level.
 - The filename is the classname with a .hh / .cc extension (is that 
protable?)
 - The advantage is that when the classes are alphabetically sorted in our 
IDE (or dir listing), the inheritance structure is viewable and classname 
lookup is fast & consequent

Example : 
class  Threaded
{
  .....
};

class CommInterface
{
...
};

class ThreadedComponent : public  Threaded
{
....
};

class ThreadedCommInterfaceComponent : public Threaded, public CommInterface
{
...
};

However, the last example shows a disadvantage of this approach : long class 
names.  For evident or clear structural differences between super class(es) 
and sub class, the superclasses may be omitted. For example, when every 
component is Threaded and implements the CommInterface, the ``Component'' 
classname is allowed.  (typdefs are not forbidden either of course)

Function names :
First a short note.  Most higher level classes will have a lot of methods. A 
class that implements one or more interfaces will soon cope with a fair 
amount of methods in its scope. Also, since we apply the technique of 
encapsulation, most attributes will require access methods.  This again 
increases the number of methods.  Therefore, we need a naming convention that 
supports quick function name lookups. The following convention reaches this 
goal : 
 - Function names start with a capital character, unless its a static, every 
subsequent word starts with a capital.
 - set / get and other prefixes should not be used as prefix, but as suffix, 
so that the names are not sorted by operation (set, get...) but by subject.
I will clarify with an example : 
using the old school method we get (alphabetically sorted):
AddColor()
AddName()
ChangeColor()
GetColor()
GetName()
GetName()
....

When one wants to know which operations can be done on the color of an 
object, you have to skim the complete function list.  On the other hand, when 
the operation is suffixed, we get :

ColorAdd()
ColorChange()
ColorGet()
NameAdd()
NameGet()  
NameSet()   // or more declarative : NameIs(....)
	     // Set and Get can be omitted when no ambiguity is possible

the functions are sorted by subject, also is also critical for the 
autogenerated documentation.

Good class design can reduce this problem too. For some classes, the 
attributes ( members variables ) are objects themselves and thus the 
set/get/add operations are in the attributes API instead of the API of the 
class, the class API only provides a method that returns a reference to the 
object:

myObject->BodyColorGet()->ColorSet( .... )  
// ColorSet() is a method of the Color class, here 'Color' can be omitted
// from the last function
// ColorSet() etc methods do not show up in the 'myObject' classes api.


Private Functions
Some prefix a private function with '_', but since C++ protects us from using 
private functions in public places, i see no need to warn the programmer/user 
with a special prefix (since privates are not visible in the API )

Function definitions / {..} blocks
Example :

void Threaded::start(int secs)
{
   if (secs > 0)
   {
      mySchedTask = scheduler->taskCreate( ... );
      mySchedTask->start();
      // some other code
   }
   // other code
}

Variable names:
Keep them unambiguous and meaningfull (i ?? a ?? b ??).
start with a non capital, subsequent words after the first take a capital, no 
'_' use.
Global and static variable names start with a 'g'.

Namespaces
There is no clear view on the number of namespace yet. Every class / exported 
method etc _must_ reside in a namespace. One (probably the main) will be 
called ''orocos''.

Makefiles
Autoconf / Automake / libtool
These projects have/enforce their own coding style by means of macros, so we 
don't have to worry about coding style of Makefiles
The online book can be found at : http://sources.redhat.com/autobook/

IDE
One can use whichever IDE (s)he uses, but there should be no trace of that in 
the code, not even in the form of comments.

Directory structure
I believe the directory structure should reflect to some extent the class 
hierarchy, mainly for closely related classes.  I have not found a set of 
'rules' that describes the relations between the location of Interfaces, 
helper classes, derived classes etc, unless that an extension class mostly 
resides in a subdirectory of the superclass and interfaces are grouped 
together in one directory.
My experience also tells me that header files and source files of the same 
class should reside in the same directory (keep them close)

Documentation 
 - Code
Doxygen :A mature project for extracting C/C++ source code documentation and 
online browsable class hierarchies. It is very flexible and recognizes many 
standards (QTDoc, JavaDoc,,,,) People used to JavaDoc will feel very 
comfortable with it.
http://www.stack.nl/~dimitri/doxygen/

 - General / manuals
LaTeX. Every manual should have a HTML/online version so that it can be 
integrated in the online Orocos documentation effort.  These html files can 
be generated in a documentation build process from the LaTeX files.


--

I'm sure I forgot some points, so please contribute.  I hope that from the 
moment i get write access to the orocos web page, i can put the styleguide in 
a clearer form online.

with kind regards,
Peter