Askemos 2000 (Archive)
home · features · download · archive

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.





border
last modification: Tue, 11 Mar 2008 15:40:59 +0100
authors: jfw,
document identifier: A849640f672ed0df0958abc0712110f3c
delivered to public at Wed, 26 Jul 2017 15:34:07 +0100
short comments


rss

pdf :: context view

search



www.jangoo.de
24 Apr 2004 DefineInsecureMode
12 Dez 2010 FreeBSD
07 Dez 2010 BALLFeatures
05 Dez 2010 ByzantineAgreement
04 Dez 2010 SQLITE
03 Dez 2010 SRS
12 Okt 2010 WebDAV
12 Sep 2010 SQL
16 Jun 2010 BALL
16 Jun 2010 CouchDB
16 Jun 2010 AskemosServer
07 Mai 2010 SystemRequirements
30 Mar 2010 ProjectsOnThePlate
30 Mar 2010 AskemosResources
30 Mar 2010 RSchemeInstall
30 Mar 2010 INSTALL
30 Mar 2010 ChickenScheme
debug-access.scm
27 Nov 2009 subscriber
development
12 Jul 2009 test
01 Jul 2009 TrustCenter
27 Dez 2008 JKomG
26 Dez 2008 FanOut
26 Dez 2008 MIME
NetBSD
NOTE
02 Mai 2006 AskemosTopMenu
18 Nov 2008 StorageAdaptor
18 Nov 2008 PStoreStorageAdapt
18 Nov 2008 OperationTips
15 Nov 2008 PCRE
04 Nov 2008 ProgrammingLanguag
09 Sep 2008 RelatedProjects
23 Jul 2008 ModuleStructure05
17 Jun 2008 NEWS
17 Jun 2008 HTML
17 Jun 2008 ACM
22 Mai 2008 HTTP
22 Mai 2008 BOSH
10 Mai 2008 AskemosBibliograph
10 Mai 2008 JerrysDreamAbstrac
20 Apr 2008 XSLT
11 Mar 2008 CodingStyle
10 Mar 2008
09 Mar 2008 MIMEConverter
BSD
07 Mar 2008 XML
06 Mar 2008 SRFI
01 Mar 2008 RFC4810






Add


home · features · download · archive