Coding rules

We have developed some coding rules (or conventions) for the project, mainly to make it easier for us to understand eachother's code. We ask you to adhere to these rules, even the ones you don't like very much, so that the whole Wonka codebase has some kind of consistent feel to it.

Linus Torvalds has this to say about the coding conventions of Linux:

This is a short document describing the preferred coding style for the linux kernel. Coding style is very personal, and I won't force my views on anybody, but this is what goes for anything that I have to be able to maintain, and I'd prefer it for most other things too. Please at least consider the points made here.
First off, I'd suggest printing out a copy of the GNU coding standards, and NOT read it. Burn them, it's a great symbolic gesture.
Linus Torvalds, in linux/Documentation/CodingStyle

... and we agree. Read what follows in that frame of mind.

Fundamental Data Types

The C language explicitly leaves many details of implementation undefined, allowing the designer of a C compiler considerable freedom. In particular, the implementation of standard types such as int is left almost completely open. For this reason, in hal/cpu/<cpu>/include/processor.h, where <cpu> is the CPU type, we define a set of types which are used throughout Wonka:

Type nameWidth etc.Corresponding
Java type
Notes
w_voidnone (C void)--
w_booleanany integer typebooleanPacked bitwise in Java boolean array
w_ubyte8 bit unsigned integer--
w_sbyte8 bit signed integerbyte
w_short16 bit signed integershort
w_ushort16 bit unsigned integer--
w_char16 bit unsigned integerchar
w_int32 bit signed integerint
w_word32 bit unsigned integer--Used for Java fields, stack items, etc.
w_size32 bit unsigned integer--Used for sizes of objects etc.
w_flags32 bit unsigned integer--Used for words holding up to 32 1-bit flags.
w_long64 bit signed integerlong
w_ulong64 bit unsigned integer--
w_float32 bit ieee754 floating-point numberfloat
w_double64 bit ieee754 floating-point numberdouble

Comments and whitespace

Block comments are written like so:

  /*
  ** My hovercraft is full of eels.
  */

Shorter, ``marginal'' comments can be written like so:

  elementCount -= removeCount;  /* Don't count the elements we will be removing */

There is no set upper limit on the width of a comment block, or on the width of a marginal comment, but please bear in mind that really long lines are really hard to read.

Any block comment that begins with `/**' (note the extra asterisk) will be automagically extracted into a section of the Reference Manual. Within such a comment block the following conventions apply:

These documentation comments chiefly occur in header files, but they may also appear in program files if the implementation details deserve to be documented in the Reference Manual.

Comments and whitespace are like currants and airbubbles in a cake: you can have too few, and you can have too many. There's also no universally accepted rule to determine what constitutes ``too few'' or ``too many''. Remember that these things are supposed to make the code easier to understand: taken to excess, they can have the opposite effect.

Header (.h) Files

Each header file should begin as follows:

ifndef _ARRAY_H
#define _ARRAY_H

/**************************************************************************
* Copyright  (c) 2001 by Acunia N.V. All rights reserved.                 *
*                                                                         *
* This software is copyrighted by and is the sole property of Acunia N.V. *
* and its licensors, if any. All rights, title, ownership, or other       *
* interests in the software remain the property of Acunia N.V. and its    *
* licensors, if any.                                                      *
*                                                                         *
* This software may only be used in accordance with the corresponding     *
* license agreement. Any unauthorized use, duplication, transmission,     *
*  distribution or disclosure of this software is expressly forbidden.    *
*                                                                         *
* This Copyright notice may not be removed or modified without prior      *
* written consent of Acunia N.V.                                          *
*                                                                         *
* Acunia N.V. reserves the right to modify this software without notice.  *
*                                                                         *
*   Acunia N.V.                                                           *
*   Vanden Tymplestraat 35      info@acunia.com                           *
*   3000 Leuven                 http://www.acunia.com                     *
*   Belgium - EUROPE                                                      *
**************************************************************************/

/*
** $Id: coding-rules.html,v 1.2 2001/11/27 15:53:21 gray Exp $
*/

and end with:


#endif /* _ARRAY_H */

The #ifdef ... #define ... #endif functions ensure that nothing terrible happens if this header file gets included twice (hard to avoid in a large project). In the comment block which follows, the $Id: ... will automatically be updated by CVS to show the current revision and the date it was checked in. The rest of the comment block (which should of course be adapted to the particular case) reminds anyone reading this file that the code belongs to someone, and tells her where to look for the legal details. (See the licensing page). A header file should contain only macros and declarations (function prototypes and externs), not definitions. The only exception is the use of static inline functions as a kind of ``typesafe macro''.

Structure and type declarations

The following illustrates a typical Wonka structure declaration:


  typedef struct w_Bubble *w_bubble;

  /**
      \subsection{w\_Bubble structure declaration}

      This is an example of a fictitious structure declaration in Wonka.
      Fields \texttt{next} and \texttt{previous} are links to the next
      and previous items in a doubly-linked list.  Field \texttt{flags}
      holds some kind of funky bitmap, and \texttt{numElements} holds
      the number of elements in the variable-length array \texttt{elements}.
  */

  typedef struct w_Bubble {
    w_bubble    next;        /* This is an informative comment          */
    w_bubble    previous;
    w_flags     flags;
    w_int       numElements; /* Try to align comments whenever possible */
    w_element  *elements;
  } w_Bubble;

This simple example already illustrates several points.