Coding convention

It is always a good idea to stick to the common coding conventions proposed by each programming language. Here we want to extend these by adding comment conventions for our group.

Generally, you should write comprehensive and precise comments in your code. It is already common to add multiple line comments for functions, explaining the input and output parameters as well as what the function does. In-line comments are for a quick explanation of the variable in line.

Additionally, to that a main code script should include a header, which includes:

  1. Project title + Subtitle
  2. Contributors
  3. Functions & Dependencies
  4. Structure/ Table of Contents
  5. Link to project folder
  6. Last updated

Example:

Matlab
1
2
3
4
5
6
7
8
9
%% Project_title: Second-level Analysis
% This script uses first-level MRI data from ... stored in ... in order to do statistical inference on group-level. 
% The main contributors are: 
% - Lastname, firstname, contact
% - Lastname, firstname, contact
% The script includes the following MATLAB packages and ... external functions from ... available under ... . 
% More information on the project you can find here ... 
%
% Last updated on ... by ... .

Further, in all scripts the most important variables need to be explained at the beginning of each coding block. These are the variable name, the size and the purpose.

Example:

Matlab
1
2
3
4
%% Block I: ROI Timeseries Extraction
% roi_coord: Coordinates of the 4 Region of Interests (1x3x4)
% voi: final timeseries, high pass filtered, from each ROI (1x150x4)
% ...