Style Guide
===========

Unless otherwise specified, follow the `Boost "Design and Programming"
guidelines`__ and `header guidelines`__.  They do not address purely stylistic
matters of indentation, spacing, and brace placement; those are addressed for
FleCSI by ``clang-format``.

__ https://www.boost.org/development/requirements.html#Design_and_Programming
__ https://www.boost.org/development/header.html

Exceptions
**********

Starting from the 2019 version:

* Optimization does matter for FleCSI, but only where the overhead it
  introduces is expected to be a significant fraction of the application's
  runtime.

* Obviously FleCSI uses certain additional libraries (like Legion).  Do not
  add further dependencies without discussion.  As a single component, there
  is no need to limit use of one part of FleCSI by another.

* The ABI concerns, especially for Windows, are irrelevant.

* ``noexcept`` has replaced exception-specifications and should be used as
  appropriate, especially for move operations.

* FleCSI uses its own unit-testing framework, not Boost's.

* The preferable line-length limit is 78 characters, so that even a diff of
  such a file avoids the line continuations used in some displays.

* Individual documentation files do not get their own copyright/license.

* The source-file header is of course different.

* FleCSI uses ``flog_assert``, not ``BOOST_ASSERT``.

* ``min`` and ``max`` do not require special treatment.

* Header and source files are suffixed with ``.hh`` and ``.cc``.

* There are no "primary directories".

* Code documentation is generated by Doxygen, prose by Sphinx.

Additional Rules
****************

* Changes purely for stylistic reasons should be rare and must appear in a
  separate commit (preferably a separate merge request).

* Class and enumeration names do not get a suffix ``_t``.

* Header names are "absolute" (*i.e.*, begin with ``flecsi/``).

* Function documentation uses the imperative mood.

Directory Structure 
*******************

The source code for the core FleCSI infrastructure is located in the
*top-level/flecsi* directory. For the most part, the subdirectories of
this directory correspond to the different namespaces in the core
infrastructure. Each of these subdirectories must contain a valid
CMakeLists.txt file. However, none of their children should have a
CMakeLists.txt file, i.e., the build system will not recurse beyond the
first level of subdirectories. Developers should use relative paths
within a CMakeLists.txt file to identify source in subdirectories.

Unit test files should be placed in the *test* subdirectory of each
namespace subdirectory. By convention, developers should not create
subdirectories within the test subdirectory.

.. vim: set tabstop=2 shiftwidth=2 expandtab fo=cqt tw=72 :