CodingStyle

Written Standards

I just came across some written standards over there: http://www.kindsoftware.com/ 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.

Please follow Riastradh's Lisp Style Rules a guide to Lisp style, written by Taylor R. Campbell; parts are focussed on or specific to Scheme.

Coding Habits

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 somewhat imperfect. (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.

Cosmetic Changes

1. 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 becomes ununderstandable.

2. Other documentation

   Executed ASAP. Please report all spelling and other bad language.

Comment Tags

There are some tags to classify comments (for grep's sake).

TODO

Things to do. Missing feature visible but harmless.

FIXME

Things to do, but misfeature might cause bugs.

KLUDGE

Good enough for now. Actually not, but whatever...

EXPORT

"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.

System Dependencies

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.

Naming Conventions

• 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.

Complexity

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.

Optimizations

Please don't try to optimize for space or speed on the expense of human understanding.

No algorithm may ever trade algorithmic complexity for either size or speed.