128 lines
4.0 KiB
Plaintext
128 lines
4.0 KiB
Plaintext
Notes on Pluto Conventions
|
|
==========================
|
|
|
|
RCSID $Id: PLUTO-CONVENTIONS,v 1.1 2004/03/15 20:35:28 as Exp $
|
|
|
|
Pluto has its own stylistic conventions. They are fairly easily
|
|
inferred by reading the code.
|
|
|
|
- sample formatting:
|
|
|
|
void
|
|
fun(char *s)
|
|
{
|
|
if (s == NULL)
|
|
{
|
|
return "";
|
|
}
|
|
else
|
|
{
|
|
switch (*s)
|
|
{
|
|
default:
|
|
s++;
|
|
/* fall through */
|
|
case '\0':
|
|
return s;
|
|
}
|
|
}
|
|
}
|
|
|
|
- a function definition has its function identifier at the margin
|
|
|
|
- indentation is in steps of 4 columns (tabstops are every 8 columns)
|
|
|
|
- try to keep lines shorter than 80 columns
|
|
|
|
- space should be canonical:
|
|
+ no line should have trailing whitespace
|
|
+ leading whitespace should use tabs where possible
|
|
+ indentation should be precise
|
|
+ there should be no empty lines at the end of a file.
|
|
|
|
- braces go on their own line, indented the same as the start of what they are part of
|
|
|
|
- switch labels are indented the same as the enclosing braces
|
|
|
|
- if a case falls through, say so explicitly
|
|
|
|
- spaces follow control flow reserved words (but not function names)
|
|
|
|
- the operand of return need not be parenthesized
|
|
|
|
- be careful with types. For example, use size_t and ssize_t.
|
|
Use const wherever possible.
|
|
|
|
- we pretend that C has a strong boolean type.
|
|
We actually define bool with constants TRUE and FALSE.
|
|
Other types cannot be used as the complete expression in a test.
|
|
Hence:
|
|
if (s == NULL)
|
|
One exception: lset_t values can be treated as booleans
|
|
(technically they are, in the original sense of the word)
|
|
|
|
|
|
- memsetting a pointer to binary zero is not guaranteed to make it NULL
|
|
|
|
- side-effects of expressions are to be avoided.
|
|
BAD: if (i++ == 9)
|
|
OK: i++;
|
|
|
|
- variables are to have as small a scope as is possible.
|
|
Move definitions into inner blocks whenever possible.
|
|
Often initializing definitions become possible and are clearer.
|
|
|
|
- within a block that has declarations, separate the declarations from
|
|
the other statements with a blank line.
|
|
|
|
- "magic numbers" are suspect. Most integers in code stand for something.
|
|
They should be given a name, and that name used consistently.
|
|
|
|
- don't use malloc/free -- use the wrappers (see defs.h)
|
|
|
|
- it is good to put comments on #else and #endif to show what
|
|
they match with. I use ! to indicate the sense of the test:
|
|
#ifdef CRUD
|
|
#else /* !CRUD */
|
|
#endif /* !CRUD */
|
|
|
|
#ifndef CRUD
|
|
#else /* CRUD */
|
|
#endif /* CRUD */
|
|
|
|
- all functions and variables that are exported from a .c file should
|
|
be declared in that file's header file. Because the .c includes the
|
|
header, the declaration and the definition will be checked by the
|
|
compiler. There is almost no excuse for the "extern" keyword
|
|
in a .c file.
|
|
|
|
- when lines are too long and expressions are to be broken, try to
|
|
break just before a binary operator. The outermost binary operator
|
|
is preferred. This is perhaps the most unconventional convention.
|
|
It allows the structure of code to be evident from a scan of the
|
|
left margin. Example:
|
|
if (next_step == vos_his_client
|
|
&& sameaddr(&c->spd.that.host_addr, &his_client))
|
|
next_step = vos_done;
|
|
and
|
|
p = oppo_instantiate(p, &c->spd.that.host_addr, &c->spd.that.id
|
|
, NULL, &our_client, &his_client);
|
|
Note the different indentation of the continuations. The continuation
|
|
of a control flow statement is not indented but other continuations are.
|
|
|
|
- Never put two statements on one line.
|
|
REALLY BAD: if (cat);
|
|
Exception: some macro definitions.
|
|
|
|
- C preprocessor macros are implemented by a kind of textual substitution.
|
|
Be sure to put parentheses around references to macro arguments and
|
|
around the whole macro body. If the body is meant to be a statement,
|
|
put braces around it instead.
|
|
|
|
#define RETURN_STF_FAILURE(f) \
|
|
{ int r = (f); if (r != NOTHING_WRONG) return STF_FAIL + r; }
|
|
|
|
- adding #include statements adds dependencies. The Makefile should be
|
|
changed to reflect them. Target "makedepend" will try to list dependencies
|
|
in a way suitable for pasting into Makefile
|