Differences between revisions 22 and 23
Revision 22 as of 2018-02-12 10:59:13
Size: 13054
Comment: Drop references to old Emacs/Debian
Revision 23 as of 2018-02-12 11:00:39
Size: 13044
Comment: Remove reference to obsolete Iceweasel
Deletions are marked like this. Additions are marked like this.
Line 263: Line 263:
This mode is especially useful when used in conjunction with the [[https://addons.mozilla.org/en-US/firefox/addon/its-all-text/|It's all text]] addon for Mozilla Firefox/Iceweasel. This mode is especially useful when used in conjunction with the [[https://addons.mozilla.org/en-US/firefox/addon/its-all-text/|It's all text]] addon for Mozilla Firefox.

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:

  • with a linefeed (LF) character, which is the UNIX convention,
  • with a carriage return plus a linefeed (CR+LF), which is the DOS convention.

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:

  • Emacs always uses UNIX convention
  • MATLAB editor uses UNIX convention under Linux, but DOS convention under Windows

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 Git 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. Programming conventions

Explicitely defined destructors should always be virtual.

2.3. 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/>.

3.2. Short-circuit versus Element-wise logical AND/OR

The Short-circuit logical AND/OR (i.e. &&, ||), returns true or false, depending on whether an entire expression evaluates to true or false. It returns this value as soon as it is known. On the other hand, the Element-wise AND/OR (i.e. &, |) returns a logical array of the compared values. Even though Matlab (and possibly Octave 3.4) substitutes in short-circuit functionality when an element-wise AND/OR is encountered in an if or while statement, Octave 3.4 issues warnings to the screen every time this situation is encountered. Hence, in Dynare, all conditional statements should make use of the short-circuit logial AND and OR.

You can read more about Short-circuit logicals here and element-wise logicals here.

3.3. recursive removal of sub-directories should be avoided

Matlab/Octave offer the option 's' in function rmdir(). This option requires to delete all inferior sub-directories. We consider this option to be extremely dangerous as we don't want a possible Dynare bug to wipe out user's entire directory trees. It shouldn't be used. We always know the name of the directories that we are creating and we should remove them one by one when needed, not recursively.

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 and Octave

There exists two Emacs modes for editing MATLAB/Octave code (with colorization and indentation):

  • A MATLAB-only mode. 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. Install it with the following code in your .emacs:

;; MATLAB mode
(autoload 'matlab-mode "matlab" "Matlab Editing Mode" t)
(setq matlab-indent-level 4)
(setq matlab-indent-function-body nil)
(autoload 'matlab-shell "matlab" "Interactive Matlab mode." t)
;; The following line makes MATLAB mode the default for editing M-files
(add-to-list 'auto-mode-alist '("\\.m\\'" . matlab-mode))
  • An Octave mode, which is able to deal with both MATLAB and Octave code. It is included in Emacs. Install it with the following code:

(setq octave-block-offset 4)
;; The following line makes Octave mode the default for editing M-files
(add-to-list 'auto-mode-alist '("\\.m\\'" . octave-mode))

Broadly speaking, the MATLAB mode has a few more features than the Octave mode; but the MATLAB mode is unable to recognize Octave-specific syntax, while the Octave mode deals with both MATLAB and Octave syntaxes.

You can have both modes installed (you still need to choose which one is the default for opening M-files). You can manually switch to the other mode using M-x matlab-mode or M-x octave-mode

The MATLAB mode lets you run MATLAB within Emacs by typing M-x matlab-shell.

The Octave mode lets you run Octave within Emacs by typing M-x run-octave.

4.5. Bison and Flex

There are (imperfect) modes for both types of files:

Download the two files on these pages, put them in ~/.emacs.d/site-lisp, and add the following to your .emacs:

(autoload 'bison-mode "bison-mode.el")
(add-to-list 'auto-mode-alist '("\\.y$" . bison-mode))
(add-to-list 'auto-mode-alist '("\\.yy$" . bison-mode))

(autoload 'flex-mode "flex-mode")
(add-to-list 'auto-mode-alist '("\\.l$" . flex-mode))
(add-to-list 'auto-mode-alist '("\\.ll$" . flex-mode))

4.6. Editing Wiki pages

The MoinMoin mode for Emacs distributed on the MoinMoin website is a little buggy. Here is a fixed version: the file is to be put in your ~/.emacs.d/site-lisp. Add the following to your .emacs:

(require 'moinmoin-mode)

You need to trigger the mode manually by typing M-x moinmoin-mode.

This mode is especially useful when used in conjunction with the It's all text addon for Mozilla Firefox.

DynareWiki: CodingStandards (last edited 2018-02-12 11:00:39 by SébastienVillemot)