pluto-conventions

This a good VPN source

Notes on Pluto Conventions
==========================

RCSID $Id: PLUTO-CONVENTIONS,v 1.2 2003/10/31 02:37:51 mcr 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;
	}
    }
}

(There is a file, pluto-style.el which defines an emacs style called
	"pluto" which implements most of this)

- 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
	(note that emacs does not preserve this)
  + 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