Coding Standards for Dynare project

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

TableOfContents

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 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 [http://en.wikipedia.org/wiki/Newline Wikipedia article on Newline]. It is also possible to make the conversion with Emacs, see [#Emacs 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 [http://www.gnu.org/prep/standards/html_node/Formatting.html#Formatting 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 [http://www.gnu.org/prep/standards/html_node/Formatting.html#Formatting GNU Coding style] on how long lines should be broken, and other matters.

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.

3. Matlab/Scilab code

The basic indentation level is set to 4 spaces.

Anchor(Emacs)

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 [http://www.gnu.org/software/emacs/manual/html_node/Mode-Line.html#Mode-Line 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 [http://matlab-emacs.sourceforge.net/ 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)

The default indentation level in Matlab mode is set to 4 spaces.

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