Reordering styles by priority, misc clean ups
This commit is contained in:
Joel Thomas Clemmer
@ -27,20 +27,20 @@ negotiable or optional. Please feel free to contact the LAMMPS core
|
||||
developers in case you need additional explanations or clarifications or
|
||||
in case you need assistance in realizing the (strict) requirements for
|
||||
your contributions. Requirements include:
|
||||
* :ref:`Licensing requirements <License>` (strict)
|
||||
* :ref:`Integration testing <IntegrationTesting>` (strict)
|
||||
* :ref:`Documentation <Documentation>` (strict)
|
||||
* :ref:`Programming language standards <ProgrammingStandards>` (strict)
|
||||
* :ref:`Build system <BuildSystem>` (strict)
|
||||
* :ref:`Command or style names <Naming>` (strict)
|
||||
* :ref:`Programming style requirements <ProgrammingStyle>` (varied)
|
||||
* :ref:`Examples <Examples>` (preferred)
|
||||
* :ref:`Error or warning messages and explanations <ErrorMessages>` (preferred)
|
||||
* :ref:`Citation reminder <Citation>` (optional)
|
||||
* :ref:`Testing <UnitTesting>` (optional)
|
||||
* :ref:`Licensing requirements <ReqLicense>` (strict)
|
||||
* :ref:`Integration testing <ReqIntegrationTesting>` (strict)
|
||||
* :ref:`Documentation <ReqDocumentation>` (strict)
|
||||
* :ref:`Programming language standards <ReqProgrammingStandards>` (strict)
|
||||
* :ref:`Build system <ReqBuildSystem>` (strict)
|
||||
* :ref:`Command or style names <ReqNaming>` (strict)
|
||||
* :ref:`Programming style requirements <ReqProgrammingStyle>` (varied)
|
||||
* :ref:`Examples <ReqExamples>` (preferred)
|
||||
* :ref:`Error or warning messages and explanations <ReqErrorMessages>` (preferred)
|
||||
* :ref:`Citation reminder <ReqCitation>` (optional)
|
||||
* :ref:`Testing <ReqUnitTesting>` (optional)
|
||||
|
||||
|
||||
.. _License:
|
||||
.. _ReqLicense:
|
||||
|
||||
Licensing requirements (strict)
|
||||
-------------------------------
|
||||
@ -70,7 +70,7 @@ that use code with a conflicting license can be split into two parts:
|
||||
Please note, that this split licensed mode may complicate including the
|
||||
contribution in binary packages.
|
||||
|
||||
.. _IntegrationTesting:
|
||||
.. _ReqIntegrationTesting:
|
||||
|
||||
Integration testing (strict)
|
||||
----------------------------
|
||||
@ -96,7 +96,7 @@ testing tools or scripts or tests themselves. This is rare. If in
|
||||
doubt, contact the LAMMPS developer that is assigned to the pull request.
|
||||
|
||||
|
||||
.. _Documentation:
|
||||
.. _ReqDocumentation:
|
||||
|
||||
Documentation (strict)
|
||||
----------------------
|
||||
@ -157,7 +157,7 @@ it for people to get started, the more likely it is that users will try
|
||||
out your new feature.
|
||||
|
||||
|
||||
.. _ProgrammingStandards:
|
||||
.. _ReqProgrammingStandards:
|
||||
|
||||
Programming language standards (strict)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -189,7 +189,7 @@ required to use those older tools for access to advanced hardware
|
||||
features or not have the option to install newer compilers or libraries.
|
||||
|
||||
|
||||
.. _BuildSystem:
|
||||
.. _ReqBuildSystem:
|
||||
|
||||
Build system (strict)
|
||||
---------------------
|
||||
@ -217,7 +217,7 @@ cmake/Modules/Packages/. Please check out how this is handled for
|
||||
existing packages and ask the LAMMPS developers if you need assistance.
|
||||
|
||||
|
||||
.. _Naming:
|
||||
.. _ReqNaming:
|
||||
|
||||
Command or Style names, file names, and keywords (strict)
|
||||
---------------------------------------------------------
|
||||
@ -231,7 +231,7 @@ established (e.g. lj for Lennard-Jones). For a compute style
|
||||
`LMP_COMPUTE_SOME_NAME_H` and the class name `ComputeSomeName`.
|
||||
|
||||
|
||||
.. _ProgrammingStyle:
|
||||
.. _ReqProgrammingStyle:
|
||||
|
||||
Programming style requirements (varied)
|
||||
---------------------------------------
|
||||
@ -244,7 +244,7 @@ the style guidelines are provided in the :doc:`programming style doc
|
||||
page <Modify_style>`.
|
||||
|
||||
|
||||
.. _Examples:
|
||||
.. _ReqExamples:
|
||||
|
||||
Examples (preferred)
|
||||
--------------------
|
||||
@ -278,7 +278,7 @@ examples/PACKAGES directory are are further described on the
|
||||
file from other folders should be re-used through symbolic links
|
||||
|
||||
|
||||
.. _ErrorMessages:
|
||||
.. _ReqErrorMessages:
|
||||
|
||||
Error or warning messages and explanations (preferred)
|
||||
------------------------------------------------------
|
||||
@ -327,7 +327,7 @@ scheme will make it easier for LAMMPS users, developers, and
|
||||
maintainers.
|
||||
|
||||
|
||||
.. _Citation:
|
||||
.. _ReqCitation:
|
||||
|
||||
Citation reminder (optional)
|
||||
-----------------------------
|
||||
@ -357,7 +357,7 @@ documentation page you provide describing your contribution. If you are
|
||||
not sure what the best option would be, please contact the LAMMPS
|
||||
developers for advice.
|
||||
|
||||
.. _UnitTesting:
|
||||
.. _ReqUnitTesting:
|
||||
|
||||
Testing (optional)
|
||||
------------------
|
||||
|
||||
@ -17,27 +17,16 @@ may serve as representative examples.
|
||||
Include files (varied)
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- system headers or from installed libraries are include with angular
|
||||
brackets (example: ``#include <vector>``), while local include file
|
||||
use double quotes (example: ``#include "atom.h"``)
|
||||
|
||||
- when including system header files from the C library use the
|
||||
C++-style names (``<cstdlib>`` or ``<cstring>``) instead of the
|
||||
C-style names (``<stdlib.h>`` or ``<string.h>``)
|
||||
|
||||
- the order of ``#include`` statements in a file ``some_name.cpp`` that
|
||||
implements a class ``SomeName`` defined in a header file
|
||||
``some_name.h`` should be as follows:
|
||||
|
||||
- ``#include "some_name.h"`` followed by an empty line
|
||||
|
||||
- LAMMPS include files e.g. ``#include "comm.h"`` or ``#include
|
||||
"modify.h"`` in alphabetical order followed by an empty line
|
||||
|
||||
- system header files from the C++ or C standard library followed by
|
||||
an empty line
|
||||
|
||||
- ``using namespace LAMMPS_NS`` or other namespace imports.
|
||||
- Header files that define a new LAMMPS style (i.e. that have a
|
||||
``SomeStyle(some/name,SomeName);`` macro in them) should only use the
|
||||
include file for the base class and otherwise use forward declarations
|
||||
and pointers; when interfacing to a library use the PIMPL (pointer
|
||||
to implementation) approach where you have a pointer to a struct
|
||||
that contains all library specific data (and thus requires the library
|
||||
header) but use a forward declaration and define the struct only in
|
||||
the implementation file. This is a **strict** requirement since this
|
||||
is where type clashes between packages and hard to find bugs have
|
||||
regularly manifested in the past.
|
||||
|
||||
- Header files, especially those defining a "style", should only use
|
||||
the absolute minimum number of include files and **must not** contain
|
||||
@ -54,16 +43,60 @@ Include files (varied)
|
||||
This also means any such file can assume that `FILE`, `NULL`, and
|
||||
`INT_MAX` are defined.
|
||||
|
||||
- Header files that define a new LAMMPS style (i.e. that have a
|
||||
``SomeStyle(some/name,SomeName);`` macro in them) should only use the
|
||||
include file for the base class and otherwise use forward declarations
|
||||
and pointers; when interfacing to a library use the PIMPL (pointer
|
||||
to implementation) approach where you have a pointer to a struct
|
||||
that contains all library specific data (and thus requires the library
|
||||
header) but use a forward declaration and define the struct only in
|
||||
the implementation file. This is a **strict** requirement since this
|
||||
is where type clashes between packages and hard to find bugs have
|
||||
regularly manifested in the past.
|
||||
- System headers or from installed libraries are include with angular
|
||||
brackets (example: ``#include <vector>``), while local include file
|
||||
use double quotes (example: ``#include "atom.h"``)
|
||||
|
||||
- When including system header files from the C library use the
|
||||
C++-style names (``<cstdlib>`` or ``<cstring>``) instead of the
|
||||
C-style names (``<stdlib.h>`` or ``<string.h>``)
|
||||
|
||||
- The order of ``#include`` statements in a file ``some_name.cpp`` that
|
||||
implements a class ``SomeName`` defined in a header file
|
||||
``some_name.h`` should be as follows:
|
||||
|
||||
- ``#include "some_name.h"`` followed by an empty line
|
||||
|
||||
- LAMMPS include files e.g. ``#include "comm.h"`` or ``#include
|
||||
"modify.h"`` in alphabetical order followed by an empty line
|
||||
|
||||
- System header files from the C++ or C standard library followed by
|
||||
an empty line
|
||||
|
||||
- ``using namespace LAMMPS_NS`` or other namespace imports.
|
||||
|
||||
|
||||
Whitespace (preferred)
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Source files should not contain TAB characters unless required by the
|
||||
syntax (e.g. in makefiles) and no trailing whitespace. Text files
|
||||
should be added with Unix-style line endings (LF-only). Git will
|
||||
automatically convert those in both directions when running on Windows;
|
||||
use dos2unix on Linux machines to convert files. Text files should have
|
||||
a line ending on the last line.
|
||||
|
||||
You can check for these issues with the python scripts in the
|
||||
:ref:`"tools/coding_standard" <coding_standard>` folder. When run
|
||||
normally with a source file or a source folder as argument, they will
|
||||
list all non-conforming lines. By adding the `-f` flag to the command
|
||||
line, they will modify the flagged files to try removing the detected
|
||||
issues.
|
||||
|
||||
|
||||
Placement of braces (strongly preferred)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
For new files added to the "src" tree, a `clang-format
|
||||
<https://clang.llvm.org/docs/ClangFormat.html>`_ configuration file is
|
||||
provided under the name `.clang-format`. This file is compatible with
|
||||
clang-format version 8 and later. With that file present, files can be
|
||||
reformatted according to the configuration with a command like:
|
||||
`clang-format -i new-file.cpp`. Ideally, this is done while writing the
|
||||
code or before a pull request is submitted. Blocks of code where the
|
||||
reformatting from clang-format yields undesirable output may be
|
||||
protected with placing a pair `// clang-format off` and `// clang-format
|
||||
on` comments around that block.
|
||||
|
||||
|
||||
Miscellaneous standards (varied)
|
||||
@ -139,44 +172,3 @@ Miscellaneous standards (varied)
|
||||
and readable by all and no executable permissions. Executable
|
||||
permissions (0755) should only be on shell scripts or python or similar
|
||||
scripts for interpreted script languages.
|
||||
|
||||
Whitespace (preferred)
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
LAMMPS uses 2 characters per indentation level and lines should be
|
||||
kept within 100 characters wide.
|
||||
|
||||
Spacing before brackets, after commas, etc.
|
||||
|
||||
Source files should not contain TAB characters unless required by the
|
||||
syntax (e.g. in makefiles) and no trailing whitespace. Text files
|
||||
should be added with Unix-style line endings (LF-only). Git will
|
||||
automatically convert those in both directions when running on Windows;
|
||||
use dos2unix on Linux machines to convert files. Text files should have
|
||||
a line ending on the last line.
|
||||
|
||||
You can check for these issues with the python scripts in the
|
||||
:ref:`"tools/coding_standard" <coding_standard>` folder. When run
|
||||
normally with a source file or a source folder as argument, they will
|
||||
list all non-conforming lines. By adding the `-f` flag to the command
|
||||
line, they will modify the flagged files to try removing the detected
|
||||
issues.
|
||||
|
||||
|
||||
Placement of braces (strongly preferred)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
On new lines for methods, when to use, etc.
|
||||
|
||||
For new files added to the "src" tree, a `clang-format
|
||||
<https://clang.llvm.org/docs/ClangFormat.html>`_ configuration file is
|
||||
provided under the name `.clang-format`. This file is compatible with
|
||||
clang-format version 8 and later. With that file present, files can be
|
||||
reformatted according to the configuration with a command like:
|
||||
`clang-format -i new-file.cpp`. Ideally, this is done while writing the
|
||||
code or before a pull request is submitted. Blocks of code where the
|
||||
reformatting from clang-format yields undesirable output may be
|
||||
protected with placing a pair `// clang-format off` and `// clang-format
|
||||
on` comments around that block.
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user