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.

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 Release Notes

  • 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

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).