From f4cfe9ffca87d83a1f1fc827ecc89d313050d757 Mon Sep 17 00:00:00 2001 From: dos-reis Date: Fri, 18 Apr 2008 03:43:13 +0000 Subject: add style guidelines --- STYLES | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 STYLES (limited to 'STYLES') diff --git a/STYLES b/STYLES new file mode 100644 index 00000000..7c9815c1 --- /dev/null +++ b/STYLES @@ -0,0 +1,48 @@ +Styles for Boot Codes +--------------------- + + The core of the OpenAxiom system is mostly written Boot. A long +time ago, Boot was essentially a Lisp DSL with a much more palatable +syntax geared specifically for writing readable codes. As such it +tended to have lots of Lispism in it. + + There days, Boot is no longer `just a syntactic sugar over Lisp', +even currently, we essentially translate to Lisp. Boot is a +programming language in of its own. In fact, we would like to remove +Lispism from Boot codes. The `rules' below are suggestions (or +guidelines) for writing `good Boot codes'. + + +* In general, you should precede your functions definitions with + ++ comments that describes the semantics of the functions, its + pre- and post-conditions. + +* Use -- comments only for non-descriptive remarks, such as in + function body. + +* Always precede your functions definitions with type declarations. + Exception to this ruke should be rare and documented. + + +* Don't use Lisp functions directly in Boot codes, except where + they are for interfacing with Lisp. + + Example: + + -- GOOD -- + first form in '(Mapping Record) => -- ... + + -- BAD -- + CAR form in '(Mapping Record) => -- ... + +* Don't use `null' to test for Boolean values, use `not' + + Example: + + -- GOOD -- + not $monitorNewworld => ... + + -- BAD -- + null $monitorNewworld => ... + + -- cgit v1.2.3