Subversion Repositories gelsvn

Andreas Bærentzen, 
December 2001

----------------------------------------------------------------------
CODING CONVENTIONS
----------------------------------------------------------------------

Coding conventions are very important if the source code is to remain
legible and tidy. Very strict conventions, however, will require too
much work of the programmer, and (if the programmer is myself) he will 
start to ignore some of the conventions in order to do things more
quickly, and then the card house topples.

Nothing that imposes too much work should be made a coding
convention. For instance, a standard comment before each function
definition sounds like a good idea, but even with a template, it is
cumbersome to add and maintain these chunks of text, so I choose to
omit them.

The philosophy behind the conventions below is that they should simply 
be standard ways of doing what a programmer does anyway and that they
should add only very little extra work.

USE OF CASE AND SPECIAL CHARACTERS
------------------------------

* Abbreviations are used only where the names would otherwise be
ludicrously long.

* Names of constants are all uppercase letters. Underscores are used to
combine words, e.g. `MAX_LEVEL'

* Names of classes and other new types are in lower case but
inter-capitalized, e.g. `class BoneMachine'

* The names of functions are lower case. Words are combined with
underscores, e.g. `int get_max()'

FUNCTION NAMING
------------------------------

* Words used

The words `get' and `set' are used in the names of functions that
assigns or retrieves the value of some state variable in a class.

E.g.

get_level
set_level

The words `find', `remove', `insert' are used in the names of
functions that access a database.

E.g.

find_node
remove_node
insert_node

The word `create' is used in the name of a function that creates and
returns a member of a class, e.g.

create_inquirer

The word `inquirer' is used in the names of functions that access
data structures. E.g.

OctreeInquirer

COMMENTING
------------------------------

* Comments are used where appropriate. DOC++ comments are used 
for all class members in .h files. There are no comments used
purely for aestethical or ``typographical'' reasons.
...

At some point I may add a standard file header. Could contain CVS
information perhaps.

FUNCTION ARGUMENTS
------------------------------

* Constructor arguments. If a class X contains a variable y that is
initialized in the contructor of X, then the argument to the
constructor should be _y, that is

X::X(_y): y(_y) {}

* Usually a function takes arguments that are constant and ``call by
reference'' arguments that may be modified. The constant arguments
should come first, then the modifiable. E.g.

        foo(const MyClass&, int, float&);

has two constant arguments followed by a float which is passed by
reference.

FILE (NAMING) CONVENTIONS
------------------------------

* All classes that are not auxiliary (i.e. used only by one particular
other class) have a header file of their own. 

* The name of the header file is that of the class + `.h'

* All non-auxiliary classes with one or more functions that are not
inline have a definition file of their own.

* The name of the definition file is that of the class + `.cc'

* The #define <macro> in the include guard uses the name of the file -
 capitalized and with dot replaced by underscore. The macro name is
preceded by two underscores

E.g.

#ifndef __BONEMACHINE_H
#define __BONEMACHINE_H

... code ....

#endif