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 (where ``\`` is used instead of ``@``), prose by Sphinx.

Additional Rules
^^^^^^^^^^^^^^^^

* 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 
^^^^^^^^^^^^^^^^^^^
Each subdirectory of ``flecsi`` has a ``CMakeLists.txt`` file which names further subdirectories (many of which are backend-specific) as needed.
Most also have ``test`` subdirectories, as do the ``topo`` subdirectories (which typically need more data files).

Commits
^^^^^^^
While exceptions must occasionally be made to each of the following, ideally each commit should

* build and pass tests (partly to support ``git bisect``)
* not add or change material changed later in the same merge request (partly to help ``git blame``)
* include the smallest subset of an overall set of changes that follows the above rules
* add or update any relevant documentation, including the :doc:`../news`
* not be a `meaningless merge`__ from the destination branch (as introduced by ``git pull``)
* have a meaningful message that follows the `50/72 rule`__
* be properly formatted per ``clang-format``
* either make only purely stylistic changes or make no such changes

__ https://docs.kernel.org/maintainer/rebasing-and-merging.html#merging-from-sibling-or-upstream-trees
__ http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Stylistic changes should be rare and are best put in their own merge request (so that they do not complicate any substantive review).
Improvements to the style of code already being modified are encouraged, so long as they do not materially interfere with review.

Expending a reasonable effort to rewrite the history of a merge request to obtain the above properties is encouraged.
The usual tool is ``git rebase -i``, although retroactive formatting is much easier with (a script that runs) ``git filter-branch``.

The name of the source branch of a merge request appears in the machine-generated commit that merges it.
Those names should therefore be meaningful; in particular, to avoid confusion they shouldn't just be that of the destination branch (as from commands like ``git checkout 2.1``).