Alan R. T. Spencer
Russell J. Garwood
Mark D. Sutton
All Palaeoware software packages should be coded using the conventions below, which are based on the Qt Coding Style.
Variables and functions start with a lower-case letter. Each consecutive word in a variable's name starts with an uppercase letter (camelCase). The only exception to this rule are the constructors and destructors of classes.
Variables are declared on a separate line, and avoid short/meaningless names.
Single character variable names are only used for counters and locals/temporaries which have an obvious purpose.
Classes always start with an upper-case letter.
Pointers or references always employ a single space between the type and '*' or '&', but no space between that and the variable name. Non-attached braces are used throughout.
Includes, defines, and variable declarations should be order as follows:
- Defines. Each on separate line, below the file header comment block. A line break to be used after if there are any includes or variable declarations following.
- Includes - .h files includes are first followed by any QT includes. One per line, with a line break between the .h and QT includes. The includes should be ordered alphabetically. A line break to be used after if there are any variable declarations following .
- Variable declarations. These should be ordered alphabetically by type, with special characteristics (e.g. static, etc) should be placed before standard variables.
Code with long functions declarations should be broken on to multiple lines if it is hard to read on screen. We recommend a standard character width of 200. However, if breaking the code on to multiple lines makes the code less readable this rule should be ignored.
Comments follow Doxygen syntax. Functions, classes and pages are commented as follows:
/**
*
* This comment explains the contents and purpose of the subsequent section of code.
*
**/
Where of utility variables can be commented as follows:
/// This variable serves the following purpose
All PalaeoWare software should have an associated user manual. It is encouraged to use Read the Docs for all versioned documentation.
Documentation should be stored under a ./docs directory in the root of the repository. Local builds can be placed in a directory ./docs_build.
All PalaeoWare software and repositories use Semantic Versioning and be compatible with the PEP 440 Version Identification and Dependency Specification.
The canonical public version identifiers MUST comply with the following scheme:
[N!]N(.N)*[{a|b|rc}N][.postN][.devN]
Public version identifiers are separated into up to five segments:
- Epoch segment: N!
- Release segment: N(.N)*
- Pre-release segment: {a|b|rc}N
- Post-release segment: .postN
- Development release segment: .devN
Software releases should be in named version branches (e.g. origin/v2.0.0) within the repository. Read the Docs will automatically parse these branch names during the document build.
For more information on Read the Docs versioning system see: https://docs.readthedocs.io/en/latest/versions.html
For more information on PEP 404 versioning rules see: https://www.python.org/dev/peps/pep-0440/
For more information of Semantic Versioning: https://semver.org/
The majority of Palaeoware code is released under the GNU General Public License. See LICENSE.md files in the repositories for further information.
All packages are free software; you can redistribute them and/or modify them 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.
Contributors to Palaeoware repositories agree to reassign the copyright of their contributions to the maintainers of the package. Please see the Contributor license agreement, and relevant discussions for R packages.
Palaeoware projects are released with a Contributor Code of Conduct. By contributing to this project you agree to abide by its terms.