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
   3. SDSL
   4. Ranges-V3
   5. SeqAn3
   6. Cereal
   7. UmeSIMD
   • 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

// ============================================================================
//                 SeqAn - The Library for Sequence Analysis
// ============================================================================
//
// Copyright (c) 2006-2018, Knut Reinert & Freie Universitaet Berlin
// Copyright (c) 2016-2018, 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/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.