diff --git a/docs/source/conventions/cxx_conventions.rst b/docs/source/conventions/cxx_conventions.rst index 22b997c..c4726ab 100644 --- a/docs/source/conventions/cxx_conventions.rst +++ b/docs/source/conventions/cxx_conventions.rst @@ -8,7 +8,8 @@ This page introduces the NWX team's coding conventions for writing C++. All pull requests are expected to adhere to these conventions. When possible ``clang-format`` will be used to enforce them; however, it is not possible to automatically enforce all of these conventions. This page is primarily targeted -at conventions which you must manually adhere to, while ``ci/lint/clang-format.in`` is +at conventions which you must manually adhere to, while +``ci/lint/clang-format.in`` is the linting file used and should be consulted for the conventions which will be automatically enforced. diff --git a/docs/source/conventions/file_structure.rst b/docs/source/conventions/file_structure.rst index 0ff0976..e46c20d 100644 --- a/docs/source/conventions/file_structure.rst +++ b/docs/source/conventions/file_structure.rst @@ -43,6 +43,38 @@ repo we are able to facilitate: the NWChemEx organization. By adhering to such standard we lower the barrier to entry for new developers. +*********************** +File Naming Conventions +*********************** + +- To avoid pitfalls related to differences in operating system behavior, all + files should be "lower_snake_case", i.e., all lowercase letters, underscores + for separating words. +- It is strongly recommended you stick to letters, numbers, and underscores + only. Notably avoid symbols like ``*``, ``?``, ``(``, ``)``, ``'``, + and ``"``. + +Extensions +========== + +- C++ header files end with ``*.hpp``, e.g., ``file_name.hpp``. +- C++ source files end with ``*.cpp``, e.g., ``file_name.cpp``. +- C++ inline implementation files end with ``*.ipp``, e.g., ``file_name.ipp``. +- CMake modules end with ``*.cmake``, e.g., ``file_name.cmake``. +- (GitHub-flavored) Markdown end with ``*.md``, e.g., ``file_name.md``. +- Python source files end with ``.py``, e.g., ``file_name.py``. +- ReStructured Text files end with ``.rst``, e.g., ``file_name.py``. + + +Exceptions +========== + +The following exceptions to the above file naming conventions are allowed: + +- CMake build systems should be stored in one or more ``CMakeLists.txt``. + - Reason for exception: CMake convention. + + ********************* Files and Directories ********************* diff --git a/docs/source/conventions/index.rst b/docs/source/conventions/index.rst index 2f147ce..f758ef5 100644 --- a/docs/source/conventions/index.rst +++ b/docs/source/conventions/index.rst @@ -30,3 +30,4 @@ Repository Conventions :maxdepth: 2 file_structure +