crp/OpenMC
1
0
Fork 0
mirror of https://github.com/openmc-dev/openmc.git synced 2026-07-27 21:55:41 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Add script to install post-commit hook, mention in devguide

Browse source
This commit is contained in:
Paul Romano 2021-08-11 13:45:29 -05:00
parent 41c66166e9
commit 664b106f64
5 changed files with 103 additions and 99 deletions
Download patch file Download diff file Expand all files Collapse all files

113
docs/source/devguide/styleguide.rst
View file

@ -12,18 +12,21 @@ adding new code in OpenMC.
C++
---
.. important:: To ensure consistent styling with little effort, this project
uses `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_. The
repository contains a ``.clang-format`` file that can be used to
automatically apply the style rules that are described below. The easiest
way to use clang-format is through a plugin/extension for your editor/IDE
that automatically runs clang-format using the ``.clang-format`` file
whenever a file is saved.
.. _styleguide_formatting:
Indentation
-----------
Automatic Formatting
--------------------
Use two spaces per indentation level.
To ensure consistent styling with little effort, this project uses `clang-format
<https://clang.llvm.org/docs/ClangFormat.html>`_. The repository contains a
``.clang-format`` file that can be used to automatically apply a consistent
format. The easiest way to use clang-format is to run
``tools/dev/install-commit-hooks.sh`` to install a post-commit hook that gets
executed each time a commit is made. In addition, you may want to configure your
editor/IDE to automatically runs clang-format using the ``.clang-format`` file
whenever a file is saved. For example, `Visual Studio Code
<https://code.visualstudio.com/docs/cpp/cpp-ide#_code-formatting>`_ includes
support for running clang-format.
Miscellaneous
-------------
@ -123,94 +126,6 @@ Variables declared constexpr or const that have static storage duration (exist
for the duration of the program) should be upper-case with underscores,
e.g., ``SQRT_PI``.
Use C++-style declarator layout (see `NL.18
<http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#nl18-use-c-style-declarator-layout>`_):
pointer and reference operators in declarations should be placed adject to the
base type rather than the variable name. Avoid declaring multiple names in a
single declaration to avoid confusion:
.. code-block:: C++
T* p; // good
T& p; // good
T *p; // bad
T* p, q; // misleading
Curly braces
------------
For a class declaration, the opening brace should be on the same line that
lists the name of the class.
.. code-block:: C++
class Matrix {
...
};
For a function definition, the opening and closing braces should each be on
their own lines. This helps distinguish function code from the argument list.
If the entire function fits on one or two lines, then the braces can be on the
same line. e.g.:
.. code-block:: C++
return_type function(type1 arg1, type2 arg2)
{
content();
}
return_type
function_with_many_args(type1 arg1, type2 arg2, type3 arg3,
type4 arg4)
{
content();
}
int return_one() {return 1;}
int return_one()
{return 1;}
For a conditional, the opening brace should be on the same line as the end of
the conditional statement. If there is a following ``else if`` or ``else``
statement, the closing brace should be on the same line as that following
statement. Otherwise, the closing brace should be on its own line. A one-line
conditional can have the closing brace on the same line or it can omit the
braces entirely e.g.:
.. code-block:: C++
if (condition) {
content();
}
if (condition1) {
content();
} else if (condition 2) {
more_content();
} else {
further_content();
}
if (condition) {content()};
if (condition) content();
For loops similarly have an opening brace on the same line as the statement and
a closing brace on its own line. One-line loops may have the closing brace on
the same line or omit the braces entirely.
.. code-block:: C++
for (int i = 0; i < 5; i++) {
content();
}
for (int i = 0; i < 5; i++) {content();}
for (int i = 0; i < 5; i++) content();
Documentation
-------------
@ -226,7 +141,7 @@ Style for Python code should follow PEP8_.
Docstrings for functions and methods should follow numpydoc_ style.
Python code should work with Python 3.4+.
Python code should work with Python 3.6+.
Use of third-party Python packages should be limited to numpy_, scipy_,
matplotlib_, pandas_, and h5py_. Use of other third-party packages must be

5
docs/source/devguide/workflow.rst
View file

@ -67,6 +67,11 @@ features and bug fixes. The general steps for contributing are as follows:
cd openmc
git checkout -b newbranch develop
3. Run ``tools/dev/install-commit-hooks.sh`` to install a post-commit hook that
runs clang-format on C++ files to apply :ref:`automatic code formatting
<styleguide_formatting>`. In addition, you may want to configure your text
editor to automatically run clang-format when saving C++ files.
3. Make your changes on the new branch that you intend to have included in
*develop*. If you have made other changes that should not be merged back,
ensure that those changes are made on a different branch.