CodingStyle

$Id$
$URL: https://svn.airt.nl/svn/trunk/source/CodingStyle $


Indentation and structure
=========================

- Indent using three spaces

- All functions must be preceded by a comment block which describes the purpose
  of that function. Following the following structure:

   /** Short description of the function. A longer description of the function
    *  may follow after the first period.
    *
    *  \param [in] $a: demo one
    *  \param [out] $b: demo two
    *
    *  \return an associative array containing the following keys, etc.
    */
   function demoFunction($a, &$b) {
      $b = $a;
      return array('return value'=>$value);
   }

- Always uses braces to delimit a block, even if there is only one line or
command. For example:

   if ($a == $b) {
      break;
   } else {
      continue;
   }

   function demoFunction() {
      /* do something */
   }

- Use single quotes ' to delimit strings wherever possible.

- Always initialise varables before using them.

- Do not break lines in a single command; it is okay to let things wrap around
  a bit

- Trailing spaces are frowned upon.


How to comment
==============
- Single line comments are prefixed like so
  // this is a comment

- Multi-line comments are prefixed like so
  /* First line of comment
   * Last line of comment
   */

- Do not use #-style comments in production code. #'s are used as a reminder
  for the developer and should be removed entirely before committing the
  changes to the repository


Using the database
==================
- Always use the functions provided to you by database.plib; never use
  pg_ functions directly!

- Before sending anything to a database, do proper input validation. This 
  includes tests like is_numeric.

- Escape strings before sending them to the database using db_escape_string().

Using SVN
=========
- Commit each self-contained change to the repository after you test it. One
  change per commit

- Use descriptive SVN commit messages