Thread: We are in need of a coding standard

Started: 2008-09-17 03:48:35
Last activity: 2008-09-17 03:48:35
Topics: SAC Developers
Kuang He
2008-09-17 03:48:35
Hi all,

Eric S. Raymond says in the chapter "Best Practices for Working with
Open-Source Developers" of his book The Art of Unix Programming:

Choose a coding standard. The debate over the choice of standard can
go on forever—regardless, it is too difficult and expensive to
maintain software built using multiple coding standards, and so some
common style must be chosen. Enforce your coding standard ruthlessly,
as consistency and cleanliness of the code are of the highest
priority; the details of the coding standard itself are a distant
second.

Although SAC is still proprietary software, some good standards are
still desirable. At least we should come up some general rules we
agree upon, for example:

- set indentation level to how many spaces (2 or 4 or 8?)

- the position of curly brackets

if (statement) { // K&R style
...
} else {
...
}

or else? (the same thing applies to for, while, do, switch statements)

void function() { // Java style
...
}

or

void
function()
{
....
}

or

void function()
{
....
}

or else?

- put spaces around operators?

a = b + c;

vs.

a=b+c;

- maximum line length for non-comment lines (72, 75, 78, 80, ...?)

- the order of #include's

#include <stdio.h> // system header files first
#include <stdlib.h>
#include <sys/wait.h> // system header files not in the /usr/include directory
// blank line
#include "myown.h" // user header files
#include "bar.h"

- #define's use variables of all uppercase letters

#define PI 3.1415926

- style of multi-line comments

/*
* this is a comment
* second line
*/

or:

/*
this is a comment
second line
*/

or:

/* this is a comment
second line */


We don't need anything fancy, just enough general rules to make the
code written by different people look similar. And we gotta stick to
them.

We also need to talk about how to convert the existing code to confirm
to our coding style once we have one. We can convert all the code
using ``indent'' once and for all. It will make things like ``cvs
diff'' between versions around that point harder to look at, but we
got to do it at some point. I've worked at a place where there is a
huge pile of ancient spaghetti C codes to maintain. The policy is no
matter what you change, you have to run ``indent'' on the files you
have modified before committing your changes. This makes the output of
``cvs diff'' (even with --ignore-all-space) almost unreadable all the
time, since people work on different files at different times.

Inputs are welcome!


Best regards,

--
Kuang He
Department of Physics
University of Connecticut
Storrs, CT 06269-3046

Tel: +1.860.486.4919
Web: http://www.phys.uconn.edu/~he/


03:24:31 v.01697673