Skip to content
Snippets Groups Projects

Changes

Page history
  • New page
  • Templates
    • Bump to clang-format 16 authored by Sébastien Villemot's avatar Sébastien Villemot
    Hide whitespace changes
    Inline Side-by-side
    Showing
    with 217 additions and 223 deletions
    CodingGuidelines.md
    View page @ 33a86bc1
    This page describes guidelines which should be followed when contributing code to Dynare. This page describes guidelines which should be followed when contributing code to Dynare.
    # General # General
    ## Spaces instead of tabs ## Spaces instead of tabs
    Source code should not contain tabulation characters. Use spaces instead. 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. This makes the indentation look the same on all machines, whatever the tabulation width is configured to.
    ## Newline convention ## Newline convention
    All source files should use the linefeed (LF) end of line convention (which is the default under macOS and GNU/Linux, but not under Windows). All source files should use the linefeed (LF) end of line convention (which is the default under macOS and GNU/Linux, but not under Windows).
    For more on the newline subject, and in particular on how to convert a file from one convention to another see the [Wikipedia article on Newline](https://en.wikipedia.org/wiki/Newline). For more on the newline subject, and in particular on how to convert a file from one convention to another see the [Wikipedia article on Newline](https://en.wikipedia.org/wiki/Newline).
    *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. *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.
    ## License and copyright ## License and copyright
    The copyright should be attributed to “Dynare Team”, and the license should be the GNU General Public License, version 3 or later (unless the code is borrowed from a third-party, in which case we must keep the pre-existing copyright notice and license). The copyright should be attributed to “Dynare Team”, and the license should be the GNU General Public License, version 3 or later (unless the code is borrowed from a third-party, in which case we must keep the pre-existing copyright notice and license).
    ## Comments ## Comments
    Abundantly comment your code (unless it is self-explanatory). Abundantly comment your code (unless it is self-explanatory).
    ## Documentation ## Documentation
    Whenever relevant, for example an option or command is added or its behaviour is modified, the reference manual should be updated. Whenever relevant, for example an option or command is added or its behaviour is modified, the reference manual should be updated.
    Whenever a new feature is added, the [new features page](NewFeatures) should be updated. Whenever a new feature is added, the [new features page](NewFeatures) should be updated.
    Whenever a bug is fixed, that is present in the stable branch, the [known bugs page](Known-bugs-present-in-the-current-stable-version) should be updated, and the bugfix should be backported to the stable branch. Whenever a bug is fixed, that is present in the stable branch, the [known bugs page](Known-bugs-present-in-the-current-stable-version) should be updated, and the bugfix should be backported to the stable branch.
    ## Testing ## Testing
    As much as possible, integration and unit tests should be added. See As much as possible, integration and unit tests should be added. See
    [CONTRIBUTING.md](https://git.dynare.org/Dynare/dynare/-/blob/master/CONTRIBUTING.md) [CONTRIBUTING.md](https://git.dynare.org/Dynare/dynare/-/blob/master/CONTRIBUTING.md)
    for more details. for more details.
    # MATLAB/Octave code # MATLAB/Octave code
    ## Indentation ## Indentation
    The basic indentation level is set to 4 spaces. The basic indentation level is set to 4 spaces.
    Function bodies should not be indented. Function bodies should not be indented.
    ## Copyright notice ## 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 update the year(s) if needed. 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 update the year(s) if needed.
    ``` ```
    % Copyright © 2022 Dynare Team % Copyright © 2022 Dynare Team
    % %
    % This file is part of Dynare. % This file is part of Dynare.
    % %
    % Dynare is free software: you can redistribute it and/or modify % Dynare is free software: you can redistribute it and/or modify
    % it under the terms of the GNU General Public License as published by % it under the terms of the GNU General Public License as published by
    % the Free Software Foundation, either version 3 of the License, or % the Free Software Foundation, either version 3 of the License, or
    % (at your option) any later version. % (at your option) any later version.
    % %
    % Dynare is distributed in the hope that it will be useful, % Dynare is distributed in the hope that it will be useful,
    % but WITHOUT ANY WARRANTY; without even the implied warranty of % but WITHOUT ANY WARRANTY; without even the implied warranty of
    % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    % GNU General Public License for more details. % GNU General Public License for more details.
    % %
    % You should have received a copy of the GNU General Public License % You should have received a copy of the GNU General Public License
    % along with Dynare. If not, see <https://www.gnu.org/licenses/>. % along with Dynare. If not, see <https://www.gnu.org/licenses/>.
    ``` ```
    ## Short-circuit versus Element-wise logical AND/OR ## 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 Octave substitutes in short-circuit functionality when an element-wise AND/OR is encountered in an `if` or `while` statement, Octave issues a warning every time this situation is encountered. Hence, in Dynare, all conditional statements should make use of the short-circuit logical AND 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 Octave substitutes in short-circuit functionality when an element-wise AND/OR is encountered in an `if` or `while` statement, Octave issues a warning every time this situation is encountered. Hence, in Dynare, all conditional statements should make use of the short-circuit logical AND and OR.
    ## Recursive removal of sub-directories should be avoided ## 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. 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.
    # Fortran code # Fortran code
    ## Fortran standard ## Fortran standard
    We follow the Fortran 2018 standard. However, features not available in gfortran 10 should not be used. We follow the Fortran 2018 standard. However, features not available in gfortran 10 should not be used.
    ## Filename extension ## Filename extension
    Use the `.f08` filename extension for Fortran source code (or the `.F08` extension if the source file needs to be preprocessed). Use the `.f08` filename extension for Fortran source code (or the `.F08` extension if the source file needs to be preprocessed).
    ## Disabling implicit typing and implicit procedure declaration ## Disabling implicit typing and implicit procedure declaration
    The following statement should be added to every program unit (module, main program, external subprogram), to disable implicit typing and implicit procedure declaration: The following statement should be added to every program unit (module, main program, external subprogram), to disable implicit typing and implicit procedure declaration:
    ``` ```
    implicit none (type, external) implicit none (type, external)
    ``` ```
    It can also be a good idea to add `implicit none` within interface blocks, when there are a lot of dummy arguments. It can also be a good idea to add `implicit none` within interface blocks, when there are a lot of dummy arguments.
    ## Indentation ## Indentation
    We follow the indentation rules applied by Emacs. We follow the indentation rules applied by Emacs.
    ## Copyright notice ## Copyright notice
    You should add the following notice in the header of your all your source files (possibly updating the year): You should add the following notice in the header of your all your source files (possibly updating the year):
    ``` ```
    ! Copyright © 2022 Dynare Team ! Copyright © 2022 Dynare Team
    ! !
    ! This file is part of Dynare. ! This file is part of Dynare.
    ! !
    ! Dynare is free software: you can redistribute it and/or modify ! Dynare is free software: you can redistribute it and/or modify
    ! it under the terms of the GNU General Public License as published by ! it under the terms of the GNU General Public License as published by
    ! the Free Software Foundation, either version 3 of the License, or ! the Free Software Foundation, either version 3 of the License, or
    ! (at your option) any later version. ! (at your option) any later version.
    ! !
    ! Dynare is distributed in the hope that it will be useful, ! Dynare is distributed in the hope that it will be useful,
    ! but WITHOUT ANY WARRANTY; without even the implied warranty of ! but WITHOUT ANY WARRANTY; without even the implied warranty of
    ! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    ! GNU General Public License for more details. ! GNU General Public License for more details.
    ! !
    ! You should have received a copy of the GNU General Public License ! You should have received a copy of the GNU General Public License
    ! along with Dynare. If not, see <https://www.gnu.org/licenses/>. ! along with Dynare. If not, see <https://www.gnu.org/licenses/>.
    ``` ```
    # C++ code # C++ code
    ## C++ standard ## C++ standard
    We follow the C++20 standard. However, C++20 features not available in GCC 10 should not be used (see [this table](https://en.cppreference.com/w/cpp/compiler_support/20) to know in which GCC version a given feature was implemented). We follow the C++20 standard. However, C++20 features not available in GCC 10 should not be used (see [this table](https://en.cppreference.com/w/cpp/compiler_support/20) to know in which GCC version a given feature was implemented).
    NB: The GCC version restriction is enforced in `meson.build`. NB: The GCC version restriction is enforced in `meson.build`.
    ## Coding guidelines ## Coding guidelines
    As much as possible, one should follow the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines). As much as possible, one should follow the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines).
    However note that we don’t apply the following rules: However note that we don’t apply the following rules:
    * SF.1: we rather use `.cc` and `.hh` as file extensions * SF.1: we rather use `.cc` and `.hh` as file extensions
    * C.12: we deliberately make some data members `const` (*e.g.* in [ComputingTasks.hh](https://git.dynare.org/Dynare/preprocessor/-/blob/master/src/ComputingTasks.hh)) * C.12: we deliberately make some data members `const` (*e.g.* in [ComputingTasks.hh](https://git.dynare.org/Dynare/preprocessor/-/blob/master/src/ComputingTasks.hh))
    ## Coding style ## Coding style
    The coding style for Dynare C++ source code is described by the following The coding style for Dynare C++ source code is described by the following
    [clang-format configuration file](https://git.dynare.org/Dynare/dynare/-/blob/master/.clang-format). [clang-format configuration file](https://git.dynare.org/Dynare/dynare/-/blob/master/.clang-format).
    This style is based on the [GNU Coding This style is based on the [GNU Coding
    style](https://www.gnu.org/prep/standards/html_node/Formatting.html#Formatting), style](https://www.gnu.org/prep/standards/html_node/Formatting.html#Formatting),
    with some modifications, notably the absence of a space before the parenthesis with some modifications, notably the absence of a space before the parenthesis
    for a function call or declaration. for a function call or declaration.
    The CI pipeline includes a test with `clang-format` to verify that the style is The CI pipeline includes a test with `clang-format` to verify that the style is
    correct, and will fail otherwise. This means that you should run `clang-format` correct, and will fail otherwise. This means that you should run `clang-format`
    locally before pushing any change to the C++ codebase. locally before pushing any change to the C++ codebase.
    Since the behaviour of `clang-format` varies slightly across versions, it is Since the behaviour of `clang-format` varies slightly across versions, it is
    necessary to stick to a specific version. We currently use version 15 of necessary to stick to a specific version. We currently use version 16 of
    `clang-format`. `clang-format`.
    ### Installing clang-format locally ### Installing clang-format locally
    Under Debian, use the `clang-format-15` package. Make sure that the generic Under Debian, use the `clang-format-16` package. Make sure that the generic
    `clang-format` package is not installed, nor any more recent version of `clang-format` package is not installed, nor any more recent version of
    `clang-format`, otherwise selection of the correct binary may fail (see below). `clang-format`, otherwise selection of the correct binary may fail (see below).
    Under MSYS2, the package `mingw-w64-x86_64-clang-15` provides the right MSYS2 and Homebrew currently do not provide version 16 of `clang-format`.
    version of `clang-format`, under the `/mingw64/opt/llvm-15/bin/` directory.
    That latter directory is not in the `PATH` by default, so it should probably be ### Applying the style with Meson
    added first in the `PATH` in order to make sure that it is used preferably to
    others (untested). When `clang-format` is installed, Meson is able to autodetect it and then
    creates a rule for reformatting the whole git repository (NB: this does not
    Homebrew currently does not provide version 15 of `clang-format`. recurse into submodules). That rule can be invoked with:
    ### Applying the style with Meson ```
    ninja -C <builddir> clang-format
    When `clang-format` is installed, Meson is able to autodetect it and then ```
    creates a rule for reformatting the whole git repository (NB: this does not
    recurse into submodules). That rule can be invoked with: It is also possible to check whether the correct style has been applied
    (without doing any reformatting):
    ``` ```
    ninja -C <builddir> clang-format ninja -C <builddir> clang-format-check
    ``` ```
    It is also possible to check whether the correct style has been applied ### Applying the style with Emacs
    (without doing any reformatting):
    ``` There exists a `clang-format` package, available through MELPA. Under Debian,
    ninja -C <builddir> clang-format-check that package is installed automatically whenever `clang-format` is installed.
    ``` It can be loaded with `(require 'clang-format)`.
    ### Applying the style with Emacs The package provides two main functions, whose names are self-explanatory:
    `clang-format-buffer` and `clang-format-region`.
    There exists a `clang-format` package, available through MELPA. Under Debian,
    that package is installed automatically whenever `clang-format` is installed. ## Copyright notice
    It can be loaded with `(require 'clang-format)`.
    You should add the following notice at the very beginning of your all your source files (possibly updating the year):
    The package provides two main functions, whose names are self-explanatory:
    `clang-format-buffer` and `clang-format-region`. ```
    /*
    ## Copyright notice * Copyright © 2023 Dynare Team
    *
    You should add the following notice at the very beginning of your all your source files (possibly updating the year): * 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
    * Copyright © 2023 Dynare Team * the Free Software Foundation, either version 3 of the License, or
    * * (at your option) any later version.
    * This file is part of Dynare. *
    * * Dynare is distributed in the hope that it will be useful,
    * Dynare is free software: you can redistribute it and/or modify * but WITHOUT ANY WARRANTY; without even the implied warranty of
    * it under the terms of the GNU General Public License as published by * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    * the Free Software Foundation, either version 3 of the License, or * GNU General Public License for more details.
    * (at your option) any later version. *
    * * You should have received a copy of the GNU General Public License
    * Dynare is distributed in the hope that it will be useful, * along with Dynare. If not, see <https://www.gnu.org/licenses/>.
    * 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 <https://www.gnu.org/licenses/>.
    */
    ```