Coding Standards for Dynare project

This page describes conventions which should be respected in Dynare source code.

1. General conventions

1.1. Spaces instead of tabs

Source code should not contain tabulation characters. Use spaces instead.

This makes the indentation look the same on all machines, whatever the tabulation width is configured to.

See Emacs section on how to replace tabs with spaces under Emacs.

1.2. Newline convention

For historical reasons, there exists two ways of marking the end of a line in a text file:

This is the reason why, when opening a DOS text file under UNIX, you may see "^M" characters (CR) at end of lines. However, this won't happen if you're using Emacs, since it is able to autodetect the convention used in the file.

The preferred convention for Dynare source code is UNIX convention.

Here is the default convention used by several editors when creating a new file:

For more on the newline subject, and in particular on how to convert a file from one convention to another see Wikipedia article on Newline. It is also possible to make the conversion with Emacs, see Emacs section.

Note: when converting a file present in the SVN repository from one convention to another, all lines will be marked as changed when comitting the new revision.

2. C++ code

2.1. Coding style

The preferred coding style for Dynare C++ source code is the GNU Coding style.

One exception is made to the GNU coding style: in a function call or declaration, it is not necessary to insert a space between a function name and the parenthesis preceding the arguments. In GNU coding style, one should normally write printf ("string"), but in Dynare one should stick to printf("string").

Here is a source code example for a class declaration:

class ABC
{
public:
  int foo(void *a);
private:
  void bar();
};

The keywords public and private should be on the same column than the class keyword, and function declarations indented with two spaces.

Here is a source code example for a function body:

int
class_name::function_name(int arg1, int arg2)
{
  if (x < foo(y, z))
    haha = bar[4] + 5;
  else
    {
      while (z)
        {
          haha += foo(z, z);
          z--;
        }
      return (++x + bar());
    }

  do
    {
      a = foo(a);
    }
  while (a > 0);

  switch (c)
    {
    case 'a':
      return (0);
    default:
      return (1);
    }
}

The basic indentation level is of 2 spaces. Braces are always put on the following line, and are indented with 2 spaces (except for namespace, class and function declarations). Note that the function name should be placed on column zero.

See also the GNU Coding style on how long lines should be broken, and other matters.

A good tool for enforcing the coding style on a C++ source file is uncrustify. It is available on both Windows and Linux. A configuration file for uncrustify, reflecting the coding style for the Dynare project, is uncrustify.cfg at the root of the Git tree. You can beautify a file with the following command:

uncrustify -c uncrustify.cfg --replace -l CPP filename.cc

/!\ On a few cases, uncrustify will give results different from Emacs. It is therefore better to run Emacs indentation routine after uncrustify, since Emacs is the authority :)

2.2. File naming conventions

C++ source files should be named with the extension .cc, and C++ headers with .hh, so that Emacs automatically enters the C++ mode when opening them.

Extensions .c and .h should only be used for pure C files.

You should add the following notice at the very beginning of your all your source files (even headers), after having replaced "2008" by the correct year(s):

/*
 * Copyright (C) 2008 Dynare Team
 *
 * This file is part of Dynare.
 *
 * Dynare is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Dynare is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Dynare.  If not, see <http://www.gnu.org/licenses/>.
 */

3. MATLAB/Octave code

The basic indentation level is set to 4 spaces.

Function bodies should not be indented.

You should add the following notice in your files, just after the help text, but leaving a blank line between the help text and the copyright notice (so that the copyright notice doesn't appear when one types help function). Don't forget to replace "2008" by the correct year(s).

% Copyright (C) 2008 Dynare Team
%
% This file is part of Dynare.
%
% Dynare is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% Dynare is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with Dynare.  If not, see <http://www.gnu.org/licenses/>.

4. Emacs howtos

4.1. Spaces instead of tabs

To ensure that Emacs uses spaces instead of tabs for indentation, you should set the variable indent-tabs-mode to nil.

This can be done in your .emacs, or via the configuration interface, via the Indent Tabs Mode option in the Editing->Indent group.

To replace tabs by spaces in the current buffer, use the command untabify: select the whole buffer with Ctrl-x h, then run the command with

Alt-x <Return> untabify <Return>

The number of spaces used to replace the tabs is set by the tab-width option (defaults to 8, found in Editing->Editing Basics configuration group).

4.2. Newline convention

While editing a file, Emacs indicates in the mode line which newline convention is used in the current buffer. The mode line is located on the lower left corner of the buffer window, and contains a colon ":" when the UNIX convention is used, or contains "(DOS)" when the DOS convention is used (for more on this subject, see the Emacs manual section on the mode line).

Here is the procedure to convert a file: suppose you are editing a file in DOS convention (indicated by (DOS) in the mode line). Then type:

Ctrl-x <Return> f unix <Return>

to convert the buffer in UNIX convention (the mode line should now display a colon ":"). Then save it via Ctrl-x Ctrl-s.

4.3. C++ code

No special configuration is required (unless you have customized your Emacs), since GNU coding style is the default for Emacs.

Emacs can be used to reindent code which doesn't follow the right coding style. Select the whole buffer with Ctrl-x h, and then run:

Alt-x indent-region <Return>

This will replace tabs with spaces, and use right indentation levels, but many conventions of the GNU Coding Style will not be enforced though. In particular, braces not placed on a line of their own will not be moved to a newline.

4.4. MATLAB code

There exists an Emacs package for colorization and indentation of MATLAB code. Under Debian, it is contained in the emacs-goodies-el package. For other systems, you can download it from MATLAB-emacs home page and you then have to install the .el file in the right location.

You should then add the following lines to your .emacs initialization file:

;; MATLAB mode
(autoload 'matlab-mode "matlab" "Matlab Editing Mode" t)
(setq auto-mode-alist (cons '("\\.m\\'" . matlab-mode) auto-mode-alist))
(autoload 'matlab-shell "matlab" "Interactive Matlab mode." t)
(setq matlab-indent-level 4)
(setq matlab-indent-function-body nil)

The default indentation level in MATLAB mode is set to 2 spaces and we want 4.

The mode allows to run a MATLAB session inside an Emacs buffer, and has many other interesting features.