diff --git a/doc/include-file-conventions.md b/doc/include-file-conventions.md index 1f206c8f88..c9f8bd5cb1 100644 --- a/doc/include-file-conventions.md +++ b/doc/include-file-conventions.md @@ -3,7 +3,7 @@ This purpose of this document is to provide a point of reference for LAMMPS developers and contributors as to what include files and definitions to put where into LAMMPS source. -Last change 2019-06-27 +Last change 2019-07-05 ## Table of Contents @@ -14,43 +14,43 @@ Last change 2019-06-27 ## Motivation -The conventions outlined in this document are supposed to help making +The conventions outlined in this document are supposed to help make maintenance of the LAMMPS software easier. By trying to achieve consistency across files contributed by different developers, it will -become easier to modify and adjust files by the code maintainers, and -overall the chance for errors or portability issues will be reduced. -Also the rules employed are supposed to minimize naming conflicts and -simplify dependencies between files (and thus speed up compilation), as -well as make otherwise hidden dependencies visible. +become easier for the code maintainers to modify and adjust files and, +overall, the chance for errors or portability issues will be reduced. +The rules employed are supposed to minimize naming conflicts and +simplify dependencies between files and thus speed up compilation. They +may, as well, make otherwise hidden dependencies visible. ## Rules Below are the various rules that are applied. Not all are enforced strictly and automatically. If there are no significant side effects, -exceptions may be possible for cases, where a full compliance to the +exceptions may be possible for cases where a full compliance to the rules may require a large effort compared to the benefit. ### Core Files Versus Package Files -All rules listed below are most strictly observed for core LAMMPS files. -Which are the files that are not part of a package and files of the +All rules listed below are most strictly observed for core LAMMPS files, +which are the files that are not part of a package, and the files of the packages MOLECULE, MANYBODY, KSPACE, and RIGID. On the other end of the spectrum are USER packages and legacy packages that predate these -rules and thus may not be fully compliant. Also new contributions -will be checked more closely, while existing code is incrementally +rules and thus may not be fully compliant. Also, new contributions +will be checked more closely, while existing code will be incrementally adapted to the rules as time and required effort permits. ### System Versus Local Header Files -All system or library provided include files are included with angular +All system- or library-provided include files are included with angular brackets (examples: `#include ` or `#include `) while include files provided with LAMMPS are included with double quotes (examples: `#include "pointers.h"` or `#include "compute_temp.h"`). For headers declaring functions of the C-library, the corresponding C++ versions should be included (examples: `#include ` or -`#include `). However, those are limited to those defined -in the C++98 standard. Some files thus must use the older style unless +`#include `). However, these includes are limited to those defined +in the C++98 standard. Some files thus must use the older style until the minimum C++ standard requirement of LAMMPS is lifted to C++11 or even beyond (examples: `#include ` versus `#include ` or `#include ` versus `#include `). @@ -60,7 +60,7 @@ or `#include ` versus `#include `). LAMMPS core files currently correspond to the C++98 standard. Files requiring C++11 or later are only permitted in (optional) packages and particularly packages that are not part of the list of commonly -used packages like MOLECULE, KSPACE, MANYBODY, or RIGID. +used packages such as MOLECULE, KSPACE, MANYBODY, or RIGID. Also, LAMMPS uses the C-style stdio library for I/O instead of iostreams. Since using both at the same time can cause problems, iostreams should @@ -72,8 +72,8 @@ Header files will typically contain the definition of a (single) class. These header files should have as few include statements as possible. This is particularly important for classes that implement a "style" and thus use a macro of the kind `SomeStyle(some/name,SomeName)`. These will -be all included in the auto-generated `"some_style.h"` files which will -result in a high potential for direct or indirect symbol name clashes. +all be included in the auto-generated `"some_style.h"` files which +results in a high potential for direct or indirect symbol name clashes. In the ideal case, the header would only include one file defining the parent class. That would typically be either `#include "pointers.h"` for @@ -85,7 +85,7 @@ be employed. The full definition will then be included into the corresponding implementation file. In the given example from above, the header file would be called `some_name.h` and the implementation `some_name.cpp` (all lower case with underscores, while the class itself would be in camel case -and no underscores, and the style name with lower case names separated by +and no underscores `SomeName`, and the style name with lower case names separated by a forward slash). ### Implementation Files @@ -124,9 +124,9 @@ which include files should be added or removed. ## Legacy Code -A lot of code predates the application of the rules in this document, -and those rules are a moving target as well. So there is going to be -significant chunks of code, that does not fully comply. This applies +A lot of code predates the application of the rules in this document +and the rules themselves are a moving target. So there are going to be +significant chunks of code that do not fully comply. This applies for example to the USER-REAXC, or the USER-ATC package. The LAMMPS developers are dedicated to make an effort to improve the compliance and welcome volunteers wanting to help with the process.