This section contains brief details of the Gadget coding standards, based on the proposals made at the 2000 DST2 meeting in Nantes, and documented in annex L7 of the DST2 progress report for that year.

Naming Conventions

Class names should always begin with a capital letter, and class names consisting of multiple words should be written with each word capitalised.

Class members, variables and functions should always start with a lower case letter. Additional words in the name should be separated by capitalising each word. The use of underscores to separate words is discouraged.

Examples:

   #class# TimeClass {
     // ...
   }

   TimeClass* currentTime;

   #void# incrementTime(TimeClass currentTime) {
     // ...
   }

Spacing, Indentation and Brackets

Only spaces should be used for indentation, two spaces for each level of indentation. A block opening curly bracket should be at the end of the line that defines the block. The matching end bracket is placed on a line of its own, at the same level of indentation as the line that starts the block. If an if block is followed by an else clause, the next block should be started on the same line as the closing curly bracket of the previous block.

An opening round bracket following a keyword (if, while, for, etc.) should be separated from the keyword with a space. There should also be a space separating the closing round bracket and the opening curly bracket, if the curly brackets are required. In function calls, the opening bracket for the function arguments should not be separated from the function name.

All mathematical and logical operators (=, <, +, etc.) should be separated from the variables they are operating on by a space before and after the operator. Similarly when variables are separated by a comma or a semi-colon, there should be a space after the separator.

Examples:

   #for# (i = 0; i < n; i++) {
     // ...
   }

   #if# (isDone()) {
     // ...
   } #else# #if# (something()) {
     // ...
   } #else# {
     // ...
   }

   doSomething(a, b, c);

Local Variables in For Loops

Due to the limitations of some compilers, variables defined and initialised in the opening of a for loop will not always have a local scope for that loop. These variables should, therefore, be defined outside the scope of the loop.

Example:

   #int# i;
   #for# (i = 0; i < n; i++) {
     // ...
   }

Method Documentation

This documentation has been generated from the source files by Doxygen (see http://www.doxygen.org for more information). To ensure that Doxygen can document all the classes, functions and variables in Gadget, these have been described with ''doxygen style'' comments that have been placed in the header files for each class. As a minimum, these comments include the \brief command to give a brief description of the object, the \param command to give a description of the parameters (if any) and the \return command to give a description of the return value (if any). More complicated objects will require more detailed descriptions.

Any non-trivial method should also have a short description in the code, in addition to any documentation in the header file.

Example:

  #**
   * \brief This will return the total number of timesteps that have taken place in the
      simulation from the start of the model simulation until a specified year and step
   * \param year is the specified year
   * \param step is the specified step
   * \return number of timesteps taken
   *#
  #int# TimeClass::calcSteps(#int# year, #int# step);

Version Control

To maintain version control of the source files, a CVS repository has been set up on the Marine Research Institute server in Reykjavik. Any user with secure shell access to the MRI server can access this repository, and a web interface to this repository is also available to allow users to browse the source code online (see http://www.hafro.is/viewcvs/viewcvs.cgi/gadget/). Any ''official'' version of the Gadget software will be tagged and released from the source code that is in the CVS repository. The CVS repository should also contain any user documents and files external to the main source code that are distributed with the source code (for example, shell scripts to help analyse the output from a Gadget simulation).

Code Compatibility

Gadget is a program that has been developed on a Unix computing platform, and is regularly compiled and run on machines running versions of Linux, Solaris and Cygwin (a Unix emulator for Microsoft Windows machines, see http://www.cygwin.com for more information). By regularly compiling and running Gadget on a variety of computing platforms, it is hoped that the source code is compatible with as many computing platforms as possible. The list of computing platforms, and C++ compilers, that Gadget is regularly tested on is:

Linux (Fedora 9), compiled using g++ version 4.3.0
Linux (Ubuntu 8.04), compiled using g++ version 4.2.3
Linux (Fedora 8), compiled using g++ version 4.1.2
Cygwin (1.5.25-14), compiled using g++ version 3.4.4-3