Coding Conventions

CACAO uses a coding style similar to the Linux kernel coding style.

Important differences are:

CACAO uses 4-character indents with 4-characters tabs. (The tabs are a historical accident, but hard to change.)
We prefer uncuddled elses. This means you should format like this:

   1 if (first) {
   2     ...
   3 }
   4 else if (second) {
   5     ...
   6 }
   7 else {
   8     ...
   9 }

Comments

$/!\$ Please comment your code! Not after writing it, but while you write it. $/!\$

Comments should explain why the code does something a certain way. Also, comments should give an overview over sections of code, so for example you only have to read one comment line to know what happens in the following block of ten C statements.

Comments should be formatted with a blank line above and below them:

   1 statement;
   2 
   3 /* Do ... because ... */
   4 
   5 work, work, work;
   6 yadda;
   7 yadda;
   8 yadda;
   9

Comments on data structures are very important! Please comment each field of each struct, in addition to a general comment on the struct:

   1 /* lock_record_t ***************************************************************
   2 
   3    Lock record struct representing an inflated ("fat") lock.
   4 
   5 *******************************************************************************/
   6 
   7 struct lock_record_t {
   8         struct threadobject *owner;          /* current owner of this monitor */
   9         s4                   count;          /* recursive lock count          */
  10         pthread_mutex_t      mutex;          /* mutex for synchronizing       */
  11         lock_waiter_t       *waiters;        /* list of threads waiting       */
  12         lock_record_t       *nextfree;       /* next in free list             */
  13 };

Every function should be preceeded by a comment explaining the intent of the function (in imperative form) and the detailed meaning of in/out parameters and the return value. Error handling semantics should also be clarified here:

   1 /* resolve_class_from_typedesc *************************************************
   2  
   3    Return a classinfo * for the given type descriptor.
   4   
   5    IN:
   6        d................type descriptor
   7        checkaccess......if true, access rights to the class are checked
   8        link.............if true, guarantee that the returned class, if any,
   9                             has been linked
  10    OUT:
  11        *result..........set to result of resolution, or to NULL if
  12                         the reference has not been resolved
  13                         In the case of an exception, *result is
  14                         guaranteed to be set to NULL.
  15   
  16    RETURN VALUE:
  17        true.............everything ok 
  18        false............an exception has been thrown
  19 
  20    NOTE:
  21        This function always resolves eagerly.
  22    
  23 *******************************************************************************/
  24 
  25 bool resolve_class_from_typedesc(typedesc *d, bool checkaccess, bool link, classinfo **result)

Naming

Choose names that are easy to grep! Do not use the same name for different things, and avoid very frequent words as names.
Names should be all-lowercase.
Functions and global variables should have a prefix indicating which module they belong to. For example stack_analyse can be found in stack.c.
Function names and global variable names should consist of all-lowercase words separated by underscore. In particular we do not like the Java convention in C code, so dontNameFunctionsLikeThis.
Function names and global variable names should not be abbreviated too much. Err on the side of spelling out too much rather than producing riddles.
Fields of structs should have all-lowercase names without underscores. In some cases underscores may be acceptable if the name would otherwise be unreadable, but normally names should be short and undivided. Upper case letters are not acceptable in field names.
Fields storing the number of items in an array should end in count. The array itself gets a plural name, so for example you have methodscount giving the number of items in methods. Avoid using just a plural word as a counter name. If you want a short name for a local variable, prepend n, or - if it is unambiguous - just use count or n.
Type names should either end with _t or be otherwise easily recognizable as types. Some structs in CACAO use the postfix info. This should only be used for very central data structures.
Local variable names may be single letters if their meaning is really obvious. Examples are:
- i for the loop index,
- c for a class being acted upon.
The prefered length for local variable names is 1-7 characters. Avoid underscores in local variable names.
Just picking random letters from the alphabet is not acceptable!

Boilerplate Code

Every source file should have the following boilerplate code at the bottom:

   1 /*
   2  * These are local overrides for various environment variables in Emacs.
   3  * Please do not remove this and leave it at the end of the file, where
   4  * Emacs will automagically detect them.
   5  * ---------------------------------------------------------------------
   6  * Local variables:
   7  * mode: c
   8  * indent-tabs-mode: t
   9  * c-basic-offset: 4
  10  * tab-width: 4
  11  * End:
  12  * vim:noexpandtab:sw=4:ts=4:
  13  */