Style Guide

TLDR;

• Style conventions, snake_case not CamelCase,
• Clang-format, based on Chromium,
• Dogxygen for code commenting, use /** ... */ for code blocks and /// for in-line commenting,
• Recommended IDE: Visual Studio Code with support for clang-format and Doxygen.
• Optimize for the reader, not the writer.

🍍 Recommend reading "Goals of the Style Guide" by Google.

Naming Conventions

• Use snake_case everywhere.
• Use complete names for functions, classes, structs, namespaces, etc. For example, get_number_of_neighbors() instead of get_num_neib() or get_num_neigbors().

C++ Version

Current code targets C++17, i.e., should not use C++2x features.

File extension

• .cxx: C++ source
• .hxx: C++ header
• .cu: CUDA source
• .cuh CUDA header

Implementation Structure

Most of gunrock's code is implemented in header files.

The true purpose of a header file is to share code amongst multiple source files. It is commonly used to separate declarations from implementations for better code management, but that is not a requirement. It is possible to write code that does not rely on header files, and it is possible to write code that is made up of just header files (the STL and Boost libraries are good examples of that). Remember, when the preprocessor encounters an #include statement, it replaces the statement with the contents of the file being referenced, then the compiler only sees the completed pre-processed code. (see How can a C++ header file include implementation?)

detail namespace

If the content of the file is not meant for inclusion and is for internal use only, consider using namespace detail and a folder detail, see graph/detail/build.hxx for an example.

Header-guard

Use the following as header-guards instead of #ifndef:

#pragma once
...

DO NOT USE:

#ifndef HEADER
#define HEADER
...
#endif // HEADER

Clang-format

clang-format is a utility to format a source code automatically according to predefined rules. These rules for gunrock are defined in .clang-format file in the root directory, based on the Chromium style. See Visual Studio Code Clang-Format extension to set up.

(vscode) To make sure CUDA file-extensions also get formatted based on the .clang-format file, be sure to add file association for .cu and .cuh files to be associated as cpp:

settings.json

"files.associations": {
        "*.cu": "cpp",
        "*.cuh": "cpp"
},

Doxygen

Preferred doxygen commenting methods are /** ... */ for code blocks, /// for in-line commenting and @ as keyword identifier (see Documenting the code for more details).

/**
 * @brief Load balancing techniques options (for now, solely for advance).
 *
 * @par Overview
 * The following enum defines load-balancing techniques supported (or to be
 * supported) within gunrock. Right now these techniques are only valid for
 * advance, but we envision future operators can also benefit from them. This
 * enum can be passed into advance template parameter list to select the
 * respective underlying load-balanced advance kernel to use. The following
 * table attempts to summarize these techniques:
 *  https://gist.github.com/neoblizz/fc4a3da5f4fc51f2f2a90753b5c49762
 *
 * @todo somehow make that gist part of the in-code comments.
 */
enum load_balance_t {
  thread_mapped,  /// 1 element per thread
  warp_mapped,    /// Equal # of elements per warp
  block_mapped,   /// Equal # of elements per block
  bucketing,      /// Davidson et al. (SSSP)
  merge_path,     /// Merrill & Garland (SpMV)
  work_stealing,  /// <cite>
};