Coding Guide

Where to write the code documentation: in .cpp or in .hpp files?

• Write short categorizing comments in the header files, to keap them relatively clean and clear. Describe the API designs and how they are used.. These comments discribe your public interface for clients. -> .hpp files.
• Write detailed comments next to the implementation files to ensure code understanding and make changes to algorithms easier. Describe the implementation alternatives / issues and decisions in the implementation: that’s for yourself and other maintainers, even someone reviewing the design as input to some next-gen system years hence. -> .cpp files.

This is a much discussed problem. You can read more about it here (exceptionshub) and here (stackoverflow).

Doxygen Commands

https://www.doxygen.nl/manual/commands.html

Coding Style

• Structs and classes should start with a capital letter.

class EnumValidator { ... }
struct AlignedSegment { ... }
enum BamFlags { ... }

• How to comment a function. We comment functions only in hpp files and keep the code in the associated cpp files. Parameter descriptions always start with a - and a lowercase letter and end without a dot.

/*! \brief Short function description.
 * 
 * /tparam something_type - description
 *
 * /param name     - description
 * /param name2    - description
 * /param namelang - description
 * /param na       - description
 * 
 * /return description
 *
 * /details A longer desctiption goes here.
 */
template <typename something_type>
out foo(name, name2, namelang, na) { ... }

• If it is a void function, we add in and out to the parameters.

/*! \brief Short function description.
 * 
 * /param[in] name          - description
 * /param[in] name2         - description
 * /param[in, out] namelang - description
 * /param[in, out] na       - description
 */
void faa(const name, const name2, & namelang, & na) { ... }

Commit Style

• We follow the rules of seqan: https://docs.seqan.de/seqan/3-master-user/about_contributing.html