Code guidelines

When you contribute new code or make changes to existing code, please consider the following guidelines.

A high-level FieldTrip function always should behave like this

[outputargs] = functionname(cfg, inputargs)

where some functions might not need inputargs and some functions might not return outputargs.

The function should always start with a help section, that explains the purpose of the function, the type of input data that it expects, the type of output data that it will produce and the configurable options that the user has to control the behaviour of the function.

Any new configuration option should have a default set at the beginning of the function. If you don't know a good default value, you should specify the default value as empty, i.e. cfg.newoption = [].

If you add a configuration option, you should check in the configuration index whether a cfg option with similar functionality already exist in another function. Use identical names for identical functionality.

SVN log entries should describe the change to the file or files. The log message should allow an end-user to realize that a recent change in the code may relate to the changed behaviour that he/she observes. The log message should also allow another developer that is familiar with the particular code to understand why the code was changed, and what part of the code is changed.

Log messages don't have to be long, but they have to be clear to the intended audience: end-users and colleague developers. Log messages should also be clear for yourself, because sometimes you'll have to go back in a function to fix problems that were introduced by your own previous change.

Examples of good and useful log messages are

changed the documentation, no change to the code

only change in whitespace and/or comments

added support for a new option

changed the logical structure of the code, instead of doing ...., it now works like ...

fixed a problem, in case ... it did ..., whereas it should be doing ...

Examples of bad log messages are

<empty>

made a change in this function

lot of small changes

In FieldTrip the interface towards the user is controlled by making only those functions publicly available that the end-user is supposed to call from the command-line or from a Matlab script. Those functions are public and should be in the main directory or in one of the module directories.

Low-level functions that are only supposed to be called by other FieldTrip functions but not by the end-user should be in the private directory.

Generally functions (i.e. in the plotting directory) have optional arguments as a pair of inputs describing the name of one property and its value. These arguments have to be handled at the very beginning inside the function, by setting a default value, like this:

function plot_mesh(bnd, varargin)
...
% get the optional input arguments
facecolor   = keyval('facecolor',   varargin); if isempty(facecolor),   facecolor='white';end
vertexcolor = keyval('vertexcolor', varargin); if isempty(vertexcolor), vertexcolor='none';end

The function keyval is specific to check syntactic consinstency of the arguments, and the if statement checks if the variable has been specified, otherwise assigns a default value. In this way the variables which are used in the function are always correctly initialized.

If you are unsure about the choices that you should make in developing new code or contributing to existing code, please ask one of the experienced developers for help. Robert, Jan-Mathijs, Ingrid and Saskia all have a good understanding of the FieldTrip programming philosophy.