|
Size: 12129
Comment:
|
← Revision 26 as of 2022-11-21 17:03:40 ⇥
Size: 189
Comment: Page moved
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| #pragma section-numbers 2 | |
| Line 4: | Line 3: |
| = Coding Standards for Dynare project = This page describes conventions which should be respected in Dynare source code. <<TableOfContents>> == General conventions == === 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. === 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 [[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 Git repository from one convention to another, all lines will be marked as changed when comitting the new revision. == C++ code == === 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. A good tool for enforcing the coding style on a C++ source file is [[http://uncrustify.sourceforge.net/|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 :) === Programming conventions === Explicitely defined destructors should always be virtual. === 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. === Copyright notice === 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/>. */ }}} == MATLAB/Octave code == The basic indentation level is set to 4 spaces. Function bodies should not be indented. === Copyright notice === 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/>. }}} === 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 [[http://www.mathworks.com/help/techdoc/ref/logicaloperatorsshortcircuit.html|here]] and element-wise logicals [[http://www.mathworks.com/help/techdoc/ref/logicaloperatorselementwise.html|here]]. <<Anchor(Emacs)>> == Emacs howtos == === 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). === 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}}}. === 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. === 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 [[http://matlab-emacs.sourceforge.net/|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 (setq auto-mode-alist (cons '("\\.m\\'" . matlab-mode) auto-mode-alist)) }}} * An Octave mode, which is able to deal with both MATLAB and Octave code. It is included in Emacs since version 19.Install it with the following code: {{{ (setq octave-block-offset 4) ;; The following line makes Octave mode the default for editing M-files (setq auto-mode-alist (cons '("\\.m\\'" . octave-mode) auto-mode-alist)) }}} 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. /!\ If you are using Debian/Ubuntu, make sure to uninstall {{{octave3.2-emacsen}}} which contains an old and buggy version of the Octave mode. 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}}}. === Editing Wiki pages === The Moin``Moin mode for Emacs distributed on the Moin``Moin website is a little buggy. [[attachment:moinmoin-mode.el|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 [[https://addons.mozilla.org/en-US/firefox/addon/its-all-text/|It's all text]] addon for Mozilla Firefox/Iceweasel. |
This page moved to https://git.dynare.org/Dynare/dynare/-/wikis/CodingGuidelines |
This page moved to https://git.dynare.org/Dynare/dynare/-/wikis/CodingGuidelines