diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index 837e2a3360..91a17789b6 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -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 ` (strict) -* :ref:`Integration testing ` (strict) -* :ref:`Documentation ` (strict) -* :ref:`Programming language standards ` (strict) -* :ref:`Build system ` (strict) -* :ref:`Command or style names ` (strict) -* :ref:`Programming style requirements ` (varied) -* :ref:`Examples ` (preferred) -* :ref:`Error or warning messages and explanations ` (preferred) -* :ref:`Citation reminder ` (optional) -* :ref:`Testing ` (optional) +* :ref:`Licensing requirements ` (strict) +* :ref:`Integration testing ` (strict) +* :ref:`Documentation ` (strict) +* :ref:`Programming language standards ` (strict) +* :ref:`Build system ` (strict) +* :ref:`Command or style names ` (strict) +* :ref:`Programming style requirements ` (varied) +* :ref:`Examples ` (preferred) +* :ref:`Error or warning messages and explanations ` (preferred) +* :ref:`Citation reminder ` (optional) +* :ref:`Testing ` (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 `. -.. _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) ------------------ diff --git a/doc/src/Modify_style.rst b/doc/src/Modify_style.rst index 41f7748e9f..a42bdd0d1f 100644 --- a/doc/src/Modify_style.rst +++ b/doc/src/Modify_style.rst @@ -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 ``), 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 (```` or ````) instead of the - C-style names (```` or ````) - -- 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 ``), 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 (```` or ````) instead of the + C-style names (```` or ````) + +- 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" ` 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 +`_ 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" ` 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 -`_ 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. - -