Coding Style
In order to keep the code maintainable we have decided upon a set
of coding rules. Some of them may seem like splitting hairs to you,
but they do make it much easier for everybody to work on code that
hasn't been written by oneself.
So here they are...
- Naming:
- Variables:
Names for variables should only consist of letters and digits.
The first letter should be a lower case one. If your variable
names consists of several words, then the first letter of each
new word should be capital. As we decided on the only
exception are the begin and end methods.
- Private Data Variables:
Names of private data variables end with an underscore.
- Typenames:
For typenames, the same rules as for variables apply. The only
difference is that the first letter should be a capital one.
- Macros:
The use of preprocessor macros is strongly discouraged. If you
have to use them for whatever reason, please use capital letters
only.
- The Exlusive-Access Macro:
Every header file traditionally begins with the definition of
a preprocessor constant that is used to make sure that each
header file is only included once. If your header file is
called 'myheaderfile.hh', this constant should be
DUNE_MYHEADERFILE_HH.
- Files:
Filenames should consist of lower case letters exclusively.
Header files get the suffix .hh, implementation files the suffix
.cc
- Indentation:
- Documentation:
Dune, as any software project of similar complexity, will stand and fall
with the quality of its documentation. Therefore it is of paramount
importance that you document well everything you do! We use the
doxygen system to extract easily-readable documentation form the
source code. Please use its syntax everywhere. In particular,
please comment all
- Method Parameters
- Template Parameters
- Return Values
- Exceptions thrown by a method
Since we all know that writing documentation is not well-liked and
is frequently defered to some vague 'next week', we herewith
proclaim the Doc-Me Dogma . It goes like this: Whatever
you do, and in whatever hurry you happen to be, please document
everything at least with a
/** \todo Please doc me! */.
That way at least the absence of documentation is documented,
and it is easier to get rid of it systematically.
- Exceptions:
The use of exceptions for error handling is encouraged. Until further
notice, all exceptions thrown are DuneEx.
- Output: printf, streams, UserWriteF?
- Should we allow 'for' and the command following it in the same line?
- Enum vs. static const:
The case is as of yet undecided...
- Debugging Code:
Global debugging code is switched off by setting the symbol NDEBUG.
In particular, all asserts are automatically removed. Use those
asserts freely!