1 files changed, 127 insertions, 0 deletions
diff --git a/programs/pluto/PLUTO-CONVENTIONS b/programs/pluto/PLUTO-CONVENTIONS
new file mode 100644
index 000000000..5288dd2bb
--- /dev/null
+++ b/programs/pluto/PLUTO-CONVENTIONS
@@ -0,0 +1,127 @@
+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