File structure and naming

General

• header-only: SeqAn is a header-only library and all functionality is implemented in header files.
• extension: Header files have the extension .hpp.
• file-names:
  • all-lower snake_case
  • only lower case standard characters [a-z] and underscore!
  • generalised singular (concept.hpp instead of concepts.hpp)
  • if all the content of a file is inside the namespace seqan3::detail, the filename shall end _detail.hpp or the file be placed in a detail sub-directory
• utf8: All files are expected to be UTF-8 encoded. Special characters are allowed in documentation and string literals, but not in regular code (function names etc) and file names.
• self-contained: every header shall include every other header that it needs.
• seqan3/core/platform.hpp: every header that doesn't include another SeqAn3 header shall include seqan3/core/platform.hpp.
• visibility: every header that is not in a detail subfolder or contains _detail in it's name is considered part of the API and may be directly included by users of the library.

Contents

1. Copyright notice:

   1. Copy from the license file or another header.
   2. Update the year if necessary.
   3. Don't add an Author line, instead add it to doc (see below).

2. File-Documentation:

   1. \file This says doxygen that the documentation block belongs to this file
   2. \brief + one-line description starting with upper case and ending in .
   3. \author your name <your AT mail.com>
   4. \ingroup MODULENAME (files don't get this!)
   5. optionally a longer description

3. Single-inclusion: #pragma once (more information); we don't use header guards.

4. Names and order of includes: (an empty line between each block, sorted alphabetically within)

   1. C system library (rarely!)
   2. C++ Standard Library, e.g.
      • #include <vector> and
      • #include <seqan3/std/ranges>, this header is in the future the same as #include <ranges>, so it will be ordered as if the prefix seqan3/std is not there.
   3. SDSL
   4. Ranges-V3 (Always #include <seqan3/std/ranges> before including any Ranges-V3 header)
   5. SeqAn3
   6. Cereal
   7. Lemon
   • All headers are always included with <header> not with "header", even SeqAn3!
   • The reasoning for this order is System → required Dependencies → SeqAn → optional Dependencies (because the inclusion of optional dependencies might depend on values/macros from other headers, especially platform.hpp)
   • Of course there are exceptions to this rule, but they should be very well argued!

5. rest of file (likely starts with a namespace opening)

Example

// -----------------------------------------------------------------------------------------------------
// Copyright (c) 2006-2020, Knut Reinert & Freie Universität Berlin
// Copyright (c) 2016-2020, Knut Reinert & MPI für molekulare Genetik
// This file may be used, modified and/or redistributed under the terms of the 3-clause BSD-License
// shipped with this file and also available at: https://github.com/seqan/seqan3/blob/master/LICENSE.md
// -----------------------------------------------------------------------------------------------------

/*!\file
 * \brief Contains many nice things.
 * \author Hannes Hauswedell <hannes.hauswedell AT fu-berlin.de>
 * \ingroup alphabet
 */

#pragma once

#include <any>
#include <type_traits>
#include <vector>

#include <range/v3/view/drop.hpp>
#include <range/v3/view/take.hpp>

#include <seqan3/range/container/concept.hpp>

// here comes the code

Exceptions

Headers only in Debug

In some cases you need headers only in DEBUG mode, e.g. when static_asserting a concept. In these cases you may include the header inside the DEBUG block, but only if this actually improves readability of the file.

10 different DEBUG block which each include different headers do not improve readability, in this case please move everything to an extra _detail.hpp.