These are some rules that should allow to maximize the outcome of the
efforts of multiple developers and help to avoid 'bad interaction' of several
people working on the same sources. They are suggestions, but I (Steffen
Seeger) think they are reasonable to stick to.
*** NEW *** Additional Namespace
rules
Using CVS
-
Run 'cvs -n update -PAd ggi' before you start commiting changes
to the repository. Save the stderr and stdout output and study them carefully
if you have told CVS about all files you want to add to or delete from
the repository. This also lists the files that you have modified, so analyze
carefully if you really want to commit changes to the main repository.
For instance QuickHacks you made during tracing down a bug must not
end up in the repository. This doesn't mean you should not add debugging
code, this is actually strongly recommended, but you should care not to
break other peoples work accidently.
-
Think twice times twice times (no typo! Think four times!) before
commiting directory structures and before placing new files anywhere in
the repository. CVS is very unkind if you want to change the direcory structure
lateron Even if it be moving a directory up one level in the tree. If this
happens to be neccessary anyway, contact the repository maintainer.
-
If you have fixed some obvious minor bugs such as typos etc., commit
them and mail the maintainers of the files changed a short bugreport. This
is just that the maintainer knows about the changes you made.
-
Before commiting fixes for major bugs that require rewriting some functions
or fundamental changes discuss this with the maintainer things you discovered
as bugs actually might not be real bugs or require other things.
-
CVS does not substitute communication between developers. Keep this always
in mind!
Coding Style
Each programmer has its own style of coding, but if there are more than
one working on the same project, it's quite useful to stick to one coding
style. For the GGI project the following rules should help to produce the
the style used. These are manly designed to enhance readability. You usually
write code once but read it a hundred times. And if not you, certainly
other people will (have to) do. So, make your code readable!
-
#defines begin with and macros are *always* written in upper case letters,
to distinct them from normal code (as e.g. macro expansion will sometimes
behave different than function calls; for instance argument expressions
might be evaluated more than once)
-
indentation is *always* done using TAB characters. Adjust your Editors
TAB width if the 8 charachters are too many for your personal taste. But
8 chars will give a clearly visible structure.
-
comments are formated as follows: (Note that the indentation is done using
TABS, as always!
/*
** a one line comment
*/
/* A comment
**
** with title and lots of text below...
*/
/* A comment without a title but
** lots of text below.
*/
each new block level is intended using one TAB character. (like the following
example). Also the function block beginning brace is placed as in this
example
void function(void)
{
block1();
{
block2();
{
block3();
}
}
}
if-statements are formatted as follows (including the extra lines before/after
the braces:
if (..expr..) {
if_block();
} else {
else_bloc();
}
*Each* block (if present) should be sourrounded by braces. (This is because
indentation makes structuring clear to the eye but not to the compiler;
braces make things clear to both the eye and the compiler and don't hurt
performance nor code size!
switch-statements are formatted as follows:
switch (..selector..) {
case item1:
do_item1();
break;
case item2:
do_item2();
break;
...
default:
do_default();
}
comments are placed on a TAB stop as right as neccessary and easily readable.
if there is something you are not sure about or you wonder about, make
a comment beginning with three question marks "???". This will allow to
grep for files that are not completely tested yet, or to get some possible
points to look at if there are errors. If there are things you intended
as a little hack (which is not considered to be clean etc.) mark it with
"!!!"". If it is more serious and may cause damage to hardware/software,
include a #warning cpp directive.
types generally like
typedef struct/enum/union ggi_name {
...
} ggi_name;
function names for kernel space routines use underscores
void kgi_do_something()
while function names for public user space functions are like
void ggiDoSomething()
and those that are userspace but internal to the library are like
void _ggiDoSomething()
Please make sure files you submit for initial checkin meet these rules,
this will speedup the checkin process and save the CVS maintainer a lot
of work.
How to code this style with Emacs?
Emacs normally interprets the <Tab> key as "indent line", and does
indent only two spaces. To make it use an indent width of eight, put
(defvar c-site-default-style "k&r")
(add-hook 'c-mode-hook
(function (lambda()
(setq c-basic-offset 8))))
in your .emacs file in your home directory. It will automatically use a
real <Tab> instead of eight spaces, too.
Unfortunately this does not allow you to use <Tab> for indenting
comments and you must use spaces there. If you know a fix, mail it to Hartmut
Nieman <niemann@cip.e-technik.uni-erlangen.de>. Thank you.