Re: Coding style & tools

Peter Soetens wrote:

> Hello,

I will post the styleguide we use next week. Perhaps this might be another
starting point. Meanwhile I would suggest to have a look at

Mats Henricson, Eric Nyquist
Programming in C++ (Rules and Recommendations)

http://www.doc.ic.ac.uk/lab/cplus/c++.rules/
http://fcas.gsfc.nasa.gov/~xingfa/tutorial/cpprules.html

Christian

>
>
> 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
>
> _______________________________________________
> Orocos mailing list
> [email protected]
> http://mail.mech.kuleuven.ac.be/mailman/listinfo/orocos

--

---------------------------------------------------------------------
Christian Schlegel
FAW Ulm (Research Institute for Applied Knowledge Processing)
PO Box 2060
D-89010 Ulm
Germany

Tel. : ++49 (731) 501 8949
Fax  : ++49 (731) 501 999
email: [email protected]
WWW  : http://www.faw.uni-ulm.de/
---------------------------------------------------------------------