GreenPolyProducts/cantera
5
0
Fork 0
mirror of https://github.com/Cantera/cantera.git synced 2025-02-25 18:55:29 -06:00
Code Issues Packages Projects Releases Wiki Activity

[Doc] Move code style guidelines into Sphinx docs

Browse Source
This commit is contained in:
Ray Speth 2024-04-26 23:01:47 -04:00 committed by Ray Speth
parent 17982b5cf9
commit c68e3f9844
4 changed files with 150 additions and 140 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
CONTRIBUTING.md
View File

@ -10,7 +10,7 @@
* Check out the existing `main` branch, then start a new feature branch for * Check out the existing `main` branch, then start a new feature branch for
your work your work
* When making changes, write code that is consistent with the surrounding code * When making changes, write code that is consistent with the surrounding code
(see the [style guidelines](#style-guidelines) below) (see the [Cantera style guidelines](https://cantera.org/dev/develop/style-guidelines.html))
* Add tests for any new features that you are implementing to either the * Add tests for any new features that you are implementing to either the
GoogleTest-based test suite or the Python test suite. GoogleTest-based test suite or the Python test suite.
* Add examples that highlight new capabilities, or update existing * Add examples that highlight new capabilities, or update existing
@ -45,142 +45,3 @@
then that code will be release under this license as well. The copyright for then that code will be release under this license as well. The copyright for
Cantera is held collectively by the contributors. If you have made a Cantera is held collectively by the contributors. If you have made a
significant contribution, please add your name to the `AUTHORS` file. significant contribution, please add your name to the `AUTHORS` file.
# Style Guidelines
* Try to follow the style of surrounding code, and use variable names that
follow existing patterns. Pay attention to indentation and spacing.
* Configure your editor to use 4 spaces per indentation level, and **never to
use tabs**.
* Avoid introducing trailing whitespace
* Limit line lengths to 88 characters when possible
* Write comments to explain non-obvious operations
* Use whitespaces to improve code readability. Examples: after commas; before and
after binary operators (`&&`/`||`/...), and comparisons (`<`/`>`/`==`/...); before and
after equality signs `=` unless used for the assignment of a default parameter. For
mathematical operators (`+`/`-`/`*`/`/` except `^`), whitespace should be added around
the operators with the lowest priority (examples: `x + y + z`, `x*2 - 1`, or
`(a+b) * (a-b)`). For additional guidance, refer to
[Python PEP-8](https://peps.python.org/pep-0008/#whitespace-in-expressions-and-statements),
where recommendations can be extrapolated to other programming languages
* Do not go out of your way to change formatting in otherwise unmodified code
* Write 'for example', 'such as', or 'that is' instead of using the Latin
abbreviations 'i.e.' and 'e.g.'.
## C++
### Doxygen Comments
* All classes, member variables, and methods should use
[Doxygen-style comments](https://www.doxygen.nl/manual/docblocks.html).
* Comments should provide brief and/or detailed descriptions. For example, comment
blocks starting with `/**` or `//!` use the autobrief feature (comments are split into
brief and detailed descriptions at the first dot `'.'`). For short comments, the C++
style `//!` is preferred; do not use `///` or `/*!` comment styles in new code.
* [Doxygen commands](https://www.doxygen.nl/manual/commands.html) should use the `@`
prefix instead of `\` in order to better differentiate from LaTeX input.
* Whenever appropriate, classes and functions should be added to
[Doxygen groupings](https://www.doxygen.nl/manual/grouping.html) using the `@ingroup`
command. Alternatively, entire code sections can be added using the `@addtogroup`
command, where grouped classes and functions are bracketed by `@{` and `@}`.
* If applicable, new features should reference literature using the `@cite` command,
with BibTeX-style entries added to `cantera.bib`. Equations can be added using
LaTeX input bracketed by `@f[` and `@f]`. In-line math expressions are enclosed by
a pair of `@f$` directives, for example `@f$ \sin(x) @f$`.
* Indicate the version added for new functions and classes with an annotation like
`@since New in %Cantera X.Y` where `X.Y` is the next Cantera version. This notation
should also be used to indicate significant changes in behavior.
### Style Guide
* Avoid defining non-trivial functions in header files
* Header files should include an 'include guard'
* Protected and private member variable names are generally prefixed with
`m_`. For most classes, member variables should not be public.
* Class names use `InitialCapsNames`
* Methods use `camelCaseNames`
* Do not indent the contents of namespaces
* Code should follow the C++17 standard, with minimum required compiler versions
GCC 7.0, Clang 4.0, MSVC 14.14 (Visual Studio 2017 version 15.7) and Intel 19.0.
* Cantera moves frequently used C++ standard namespace types and functions into the
declarative region, meaning that the `std` scope resolution can be omitted. This
applies to the following: `string`, `vector`, `map`, `set`, `pair`, `shared_ptr`,
`make_shared`, `unique_ptr`, `make_unique` and `function`. Example: use `string`
instead of `std::string`; a `using namespace std;` declaration is not required.
* Avoid manual memory management (that is, `new` and `delete`), preferring to use
standard library containers, as well as `unique_ptr` and `shared_ptr` when dynamic
allocation is required.
* Portions of Boost which are "header only" may be used. If possible, include
Boost header files only within .cpp files rather than other header files to
avoid unnecessary increases in compilation time. Boost should not be added
to the public interface unless its existence and use is optional. This keeps
the number of dependencies low for users of Cantera. In these cases,
`CANTERA_API_NO_BOOST` should be used to conditionally remove Boost dependencies.
* While Cantera does not specifically follow these rules, the following style
guides are useful references for possible style choices and the rationales behind them.
* The Google C++ Style Guide: https://google.github.io/styleguide/cppguide.html
* http://geosoft.no/development/cppstyle.html
* For any new code, do *not* use the `doublereal` and `integer` typedefs for the
basic types `double` and `int`, but also do not go out of your way to change
uses of these in otherwise unmodified code.
* Initialize member variables with their declarations, when possible, rather than using
constructor-based initialization.
## Python
### Sphinx comments
* Cantera Python documentation is based on the Python documentation generator
[Sphinx](https://www.sphinx-doc.org/en/master/index.html)
* All classes, member variables, and methods should include
[Python docstrings](https://peps.python.org/pep-0257/#what-is-a-docstring)
* Docstrings should use annotations compatible with
[automatic documentation generation from code](https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html).
For guidance, refer to existing Cantera documentation or online tutorials (see
[example](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html))
* Indicate the version added for new functions and classes with an annotation like
`.. versionadded:: X.Y` where `X.Y` is the next Cantera version. Significant changes
in behavior should be indicated with `.. versionchanged:: X.Y`.
### Style Guide
* Style generally follows PEP8 (https://www.python.org/dev/peps/pep-0008/)
* Code in `.py` and `.pyx` files needs to be written to work with Python 3
* The minimum Python version that Cantera supports is Python 3.8, so code should only
use features added in Python 3.8 or earlier
* Please use double quotes in all new Python code
## C#
* C# coding conventions should follow https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions
* All identifiers should follow the naming conventions in the above document including
* Prefixing with `_` for private instance fields (`_foo`, unlike C++)
* Prefixing with `s_` for private static fields (`s_bar`), `t_` for private
`[ThreadStatic]` fields (`t_baz`).
* Initial caps names for class methods (`DoSomething()`, unlike C++)
* Give the opening brace of a statement block its own line (unlike C++), except empty
blocks, which may be written as an `{ }` (for example, a constructor which calls
a base-class constructor only).
* Use only one statement per line.
* Always use statement blocks (`{ ... }`) for the bodies of statements that can take
either a statement block or a single statement (`if`, `for`, etc.)
* Use file-scoped namespaces in each new file.
* Do not take any extra Nuget dependencies in the `Cantera.csproj` project.
* Use C# XML Doc-Comments on types and members, including at least the `<summary>` tag.
Always include a doc comment for types, but for members with self-explanatory names,
you may omit the doc comment and suppress the build error that would be thrown with
`#pragma warning disable/restore CS1591`.
* C# doc-comments use `///`, unlike Cantera's preferred use of `//!` for C++
* Do not expose any code requiring the `unsafe` keyword via a public API
(pointers, the `fixed` statement, etc). Pointers are used for the high-performance
interop layer with the native Cantera library, but such access should have a
“safe” wrapper, such as a `Span<T>` or a managed array.
* Do not allow exceptions to pass uncaught out of a callback invoked from native code,
as the interop layer cannot marshall exceptions between managed and native code,
and the process will crash. Use `CallbackException.Register()` within a catch-all
block to log the exception for later throwing back in managed code.
* The primary API for accessing Cantera is the `Application` class, which handles
required static initialization of the library. When exposing a new wrapper for CLib
functionality, do not expose a public constructor. Rather, mark the constructor
`internal` and wrap it in an appropriate factory method in the `Application` class
(`public static CreateFoo(string filename) { ... }`).

5
doc/sphinx/develop/doc-formatting.md
View File

@ -55,3 +55,8 @@ This page provides some notes on useful syntax for writing in these various form
## Useful Doxygen syntax ## Useful Doxygen syntax
- Linking to a Sphinx page: `[link text](../reference/science/phasethermo/lattice.html)` - Linking to a Sphinx page: `[link text](../reference/science/phasethermo/lattice.html)`
- Citations: `@cite authorYYYY` will generate a numbered citation like `[8]`, assuming
`authorYYYY` is a key in `doc/doxygen/cantera.bib`.
- Equations can be added using LaTeX input bracketed by `@f[` and `@f]`.
- In-line math expressions are enclosed by a pair of `@f$` directives, for example
`@f$ \sin(x) @f$`.

2
doc/sphinx/develop/index.md
View File

@ -51,11 +51,13 @@ reactor-integration
This section is a work in progress. This section is a work in progress.
``` ```
- [](style-guidelines)
- [](doc-formatting) - [](doc-formatting)
```{toctree} ```{toctree}
:caption: Adding New Features to Cantera :caption: Adding New Features to Cantera
:hidden: :hidden:
style-guidelines
doc-formatting doc-formatting
``` ```

142
doc/sphinx/develop/style-guidelines.md Normal file
View File

@ -0,0 +1,142 @@
# Code Style Guidelines
The following style guidelines are recommended for all new code added to Cantera.
Following these guidelines will simplify the review process for pull requests and make
it easier for others to understand your code in the context of Cantera as a whole.
## General Style
* Try to follow the style of surrounding code, and use variable names that follow
existing patterns. Pay attention to indentation and spacing.
* Configure your editor to use 4 spaces per indentation level, and **never to use
tabs**.
* Avoid introducing trailing whitespace
* Limit line lengths to 88 characters when possible
* Write comments to explain non-obvious operations
* Use whitespace to improve code readability. Examples:
* after commas
* before and after binary operators (`&&`/`||`/...) and comparisons (`<`/`>`/`==`/...)
* before and after equality signs `=` unless used for the assignment of a default
parameter.
* For mathematical operators (`+`/`-`/`*`/`/` except `^`), whitespace should be added
around the operators with the lowest priority (examples: `x + y + z`, `x*2 - 1`, or
`(a+b) * (a-b)`).
* For additional guidance, refer to [Python
PEP-8](https://peps.python.org/pep-0008/#whitespace-in-expressions-and-statements),
where recommendations can be extrapolated to other programming languages
* Do not go out of your way to change formatting in otherwise unmodified code
* Write 'for example', 'such as', or 'that is' instead of using the Latin abbreviations
'i.e.' and 'e.g.'.
## C++
* Avoid defining non-trivial functions in header files
* Header files should include an 'include guard'
* Protected and private member variable names are generally prefixed with `m_`. For most
classes, member variables should not be public.
* Class names use `InitialCapsNames`
* Methods use `camelCaseNames`
* Do not indent the contents of namespaces
* Code should follow the C++17 standard, with minimum required compiler versions GCC
7.0, Clang 4.0, MSVC 14.14 (Visual Studio 2017 version 15.7) and Intel 19.0.
* Cantera moves frequently used C++ standard namespace types and functions into the
declarative region, meaning that the `std` scope resolution can be omitted. This
applies to the following: `string`, `vector`, `map`, `set`, `pair`, `shared_ptr`,
`make_shared`, `unique_ptr`, `make_unique` and `function`. Example: use `string`
instead of `std::string`; a `using namespace std;` declaration is not required.
* Avoid manual memory management (that is, `new` and `delete`), preferring to use
standard library containers, as well as `unique_ptr` and `shared_ptr` when dynamic
allocation is required.
* Portions of Boost which are "header only" may be used. If possible, include Boost
header files only within .cpp files rather than other header files to avoid
unnecessary increases in compilation time. Boost should not be added to the public
interface unless its existence and use is optional. This keeps the number of
dependencies low for users of Cantera. In these cases, `CANTERA_API_NO_BOOST` should
be used to conditionally remove Boost dependencies.
* While Cantera does not specifically follow these rules, the following style guides are
useful references for possible style choices and the rationales behind them.
* [The Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)
* [GeoSoft C++ Programming Style Guidelines](http://geosoft.no/development/cppstyle.html)
* For any new code, do *not* use the obsolete `doublereal` and `integer` typedefs for
the basic types `double` and `int`, but also do not go out of your way to change uses
of these in otherwise unmodified code.
* Initialize member variables with their declarations, when possible, rather than using
constructor-based initialization.
### Doxygen Comments
* All classes, member variables, and methods should use
[Doxygen-style comments](https://www.doxygen.nl/manual/docblocks.html).
* Comments should provide brief and/or detailed descriptions. For example, comment
blocks starting with `/**` or `//!` use the autobrief feature (comments are split into
brief and detailed descriptions at the first dot `'.'`). For short comments, the C++
style `//!` is preferred; do not use `///` or `/*!` comment styles in new code.
* [Doxygen commands](https://www.doxygen.nl/manual/commands.html) should use the `@`
prefix instead of `\` in order to better differentiate from LaTeX input.
* Whenever appropriate, classes and functions should be added to
[Doxygen groupings](https://www.doxygen.nl/manual/grouping.html) using the `@ingroup`
command. Alternatively, entire code sections can be added using the `@addtogroup`
command, where grouped classes and functions are bracketed by `@{` and `@}`.
* If applicable, new features should reference literature using the `@cite` command,
with BibTeX-style entries added to `cantera.bib`.
* Indicate the version added for new functions and classes with an annotation like
`@since New in %Cantera X.Y` where `X.Y` is the next Cantera version. This notation
should also be used to indicate significant changes in behavior.
## Python
### Style Guide
* Style generally follows [PEP8](https://www.python.org/dev/peps/pep-0008/)
* The minimum Python version that Cantera supports is Python 3.8, so code should only
use features added in Python 3.8 or earlier
* Please use double quotes in all new Python code
### Sphinx comments
* Cantera Python documentation is based on the Python documentation generator
[Sphinx](https://www.sphinx-doc.org/en/master/index.html)
* All classes, member variables, and methods should include
[Python docstrings](https://peps.python.org/pep-0257/#what-is-a-docstring)
* Docstrings should use annotations compatible with
[autodoc](https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html).
For guidance, refer to existing Cantera documentation or online tutorials (see
[example](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html))
* Indicate the version added for new functions and classes with an annotation like
`.. versionadded:: X.Y` where `X.Y` is the next Cantera version. Significant changes
in behavior should be indicated with `.. versionchanged:: X.Y`.
## C#
* C# coding conventions should follow https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions
* All identifiers should follow the naming conventions in the above document including
* Prefixing with `_` for private instance fields (`_foo`, unlike C++)
* Prefixing with `s_` for private static fields (`s_bar`), `t_` for private
`[ThreadStatic]` fields (`t_baz`).
* Initial caps names for class methods (`DoSomething()`, unlike C++)
* Give the opening brace of a statement block its own line (unlike C++), except empty
blocks, which may be written as an `{ }` (for example, a constructor which calls
a base-class constructor only).
* Use only one statement per line.
* Always use statement blocks (`{ ... }`) for the bodies of statements that can take
either a statement block or a single statement (`if`, `for`, etc.)
* Use file-scoped namespaces in each new file.
* Do not take any extra Nuget dependencies in the `Cantera.csproj` project.
* Use C# XML Doc-Comments on types and members, including at least the `<summary>` tag.
Always include a doc comment for types, but for members with self-explanatory names,
you may omit the doc comment and suppress the build error that would be thrown with
`#pragma warning disable/restore CS1591`.
* C# doc-comments use `///`, unlike Cantera's preferred use of `//!` for C++
* Do not expose any code requiring the `unsafe` keyword via a public API
(pointers, the `fixed` statement, etc.). Pointers are used for the high-performance
interop layer with the native Cantera library, but such access should have a
“safe” wrapper, such as a `Span<T>` or a managed array.
* Do not allow exceptions to pass uncaught out of a callback invoked from native code,
as the interop layer cannot marshall exceptions between managed and native code,
and the process will crash. Use `CallbackException.Register()` within a catch-all
block to log the exception for later throwing back in managed code.
* The primary API for accessing Cantera is the `Application` class, which handles
required static initialization of the library. When exposing a new wrapper for CLib
functionality, do not expose a public constructor. Rather, mark the constructor
`internal` and wrap it in an appropriate factory method in the `Application` class
(`public static CreateFoo(string filename) { ... }`).