I just came across some written standards over there:
kindly try to adhere.
Standard is better than better!
Even if we would start to provide our own,
we would probably end up with something similar.
Riastradh's Lisp Style Rules
a guide to Lisp style, written by Taylor R. Campbell; parts are focussed on or specific to Scheme.
First read a bit about eXtreme Programming. I recommend the original
book eXtreme Programming explained from Kent Beck ISBN0-201-61641-6
and get a second pair of eyes looking at your source.
I understand that it's not always possible to be two person while
coding, moreover coding is sometimes really boring for the 2nd one.
So have people close while doing the complicated parts. If nothing
else available use email and irc frequently (irc in private channel).
Second please understand, that the implementation is by design
(If you did your home work above, that'll be easier.)
The implementation shall be good enough
and able to perform what
Clay Shirky calls
Adaptive Radiation (see EvolutionGentechnik)
in favor of best of breed and highly specialization.
Third never change two logical independent things at once. If you
did, good luck. I'm not going to look at such a diff.
For source files
Cosmetic changes Should be executed ASAP if they modify API's and
deferred until the file in question is to be changed anyway or
Executed ASAP. Please report all spelling and other bad language.
There are some tags to classify comments (for grep's sake).
- Things to do. Missing feature visible but harmless.
- Things to do, but misfeature might cause bugs.
- Good enough for now. Actually not, but whatever...
- "Defined" API of the module.
Global Variables and Side Effects
You better have a really good reason for that! Reconfiguration at
runtime would be a valid example, if reasonable.
All side effects MUST be commented.
Are best avoided. E.e., the rscheme module system is quite useful
but the code doesn't rely on it even though I'm heavily tempted. The
same goes for the object system in the inner kernel.
Those things, which are system dependent anyway or need it for
performance are free from this rule.
Names are chosen in a way that they form some understandable text
in the context of intended applications. Don't care for the
definition context when choosing names. Consequently we'll
frequently rename until the API is stable.
A name shall say what it is meant for, not what the implementation
does. (This can easily rule out get-foo and set-bar! style names.)
Actions are typically verbs, while data objects are nouns. Global
data objects prefixed with "the-".
The larger the scope, the better chosen the name.
Sometime I choose worse names, when I believe that something does
most of what it should do. When the function is later completed
I replace step by step all uses of the old version.
Procedures with side effects end in an exclamation mark!
A procedure counts as "with side effect" if it's possible to call
it in a way that the side effect is visible. Internal uses of set!
(and others), cached versions of procedures with internal state etc.
Don't count here - but they MUST be commented anyway.
The following naming conventions are only mandatory for the kernel,
recommended for all compiled code.
- Even without modules there must be no name clash
(portability to other schemes).
- Names prefixed with module.
Usually I'm more proud of the implementation details of my programs
than of what it does exactly. That's different here, I'm proud of
the over all structure and most things are optimized for human
understanding. This implies they are implemented "straight forward"
and there is some space for optimization for both speed and memory.
All algorithm, which operate on variable size data are (supposed
to be) of lowest known complexity (currently this means solved in
linear time). This means: optimization efforts can be traded for
hardware especially since the software is coded functionality and
highly threaded anyway.
Please don't try to optimize for space or speed on the expense of
No algorithm may ever trade algorithmic complexity for either size