Library structure

There are three structures or hierarchies in the library:

1. Filesystem hierarchy
2. Module hierarchy (almost identical to filesystem hierarchy)
3. Namespace hierarchy

Modules and sub-modules

• The library is structured into modules and sub-modules.
• Modules are sub-directories of the top-level include directory.
• Sub-modules are all sub-directories of module directories with the exception of sub-folders called detail (see below).
• Modules and sub-modules may contain a detail folder that does not constitute a sub-module, it belong the (sub-)module it is in and contains implementation detail (all headers inside shall not be included by consumers of the library).
• All top-level entities in

Header Files

General notes

• 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)
• 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 (e.g. alphabet, core ...)
   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 headers (rarely)
   2. C++ Standard Library headers
   3. SDSL headers (in <>)
   4. Ranges-V3 headers (in <>)
   5. SeqAn3 headers (also in <> !)

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

Example

// ============================================================================
//                 SeqAn - The Library for Sequence Analysis
// ============================================================================
//
// Copyright (c) 2006-2017, Knut Reinert & Freie Universitaet Berlin
// Copyright (c) 2016-2017, Knut Reinert & MPI Molekulare Genetik
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
//     * Redistributions of source code must retain the above copyright
//       notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above copyright
//       notice, this list of conditions and the following disclaimer in the
//       documentation and/or other materials provided with the distribution.
//     * Neither the name of Knut Reinert or the FU Berlin nor the names of
//       its contributors may be used to endorse or promote products derived
//       from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL KNUT REINERT OR THE FU BERLIN BE LIABLE
// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
// DAMAGE.
//
// ============================================================================

/*!\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/container/concepts.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.

Namespaces

SeqAn namespaces

• namespace seqan3: everything, except the following exceptions
• namespace seqan3::detail: all free/global functions, metafunctions, static variables and class definitions that are considered implementation detail and not part of the API
  • if you write lot's of code that is specific to a module or file and may collide with other implementations, you can create sub-namespaces under detail
• namespace seqan3::literals: seqan-defined literals
• namespace seqan3::action: seqan-defined actions
• namespace seqan3::view: seqan-defined views
• namespace std: overloads of std:: functions like std::begin (rarely)
• nothing should be in the global namespace
• never have using namespace ... in a header file

Syntax

• braces go on newline
• closing braces shall be documented
• there is no indention!
• for better readability and because we don't indent, nested namespaces are not declared inside parent, but separately and with full name

Example

namespace seqan3::detail
{

void my_non_public_function()
{
   // ...
}

} // namespace seqan3::detail 

namespace seqan3
{

void my_public_function()
{
    detail::my_non_public_function();
    // ...
}

} // namespace seqan3