General Code Guidelines - jimmytwei/oneAPI-samples GitHub Wiki

We are defining our guidelines to drive the following 5 objectives:

  1. Emphasize KISS – Keep it Simple and Short​ -- Minimize the code you need to explain​
  2. Write clean C++ code​
  3. Use consistent variable and type naming​
  4. Use consistent source code formatting​
  5. Samples should be coded using DPC++ idioms and not directly use DPCT runtime functions unless demonstrating a DPCT workflow.

To make these objectives practical we need to choose specific rules to drive consistency

  • "The C++ Core Guidelines" answer language questions.
  • "Google Coding Style" drives consistent variable and type naming and source formatting.
  • The clang-format tool with the -style=google option is used to enforce consistent source formatting. clang-format -style=google -i file.cpp

We have found that a few modifications of the default style guidelines are preferred in the samples.

  • Fewer source lines where possible​
  • Use auto for declaring variables if it helps to shorten line length​ and does not obscure the concept being taught
  • Simple scalar types over objects when equivalent​
  • std:: types over user-defined types when equivalent​
  • The DPC++ .parallel_for() over SYCL .parallel_for()​
    • NOTE: to build DPC++ .parallel_for() requires the option -fsycl-unnamed-lambda (default behavior). ​
  • Defining the default queue instead of over-specifying the selector​
  • Naming const values as variables.
    • Do not use the k prefix on const value names unless you are defining a "magic constant" which should be emphasized
  • Use \n vs std::endl, unless an explicit flush is required

Source formatting

  • C++ files have extension .cpp​
  • C++ header files have extension .hpp​
  • Enforce via clang-format​:
    • clang-format -style=google -i file.cpp
⚠️ **GitHub.com Fallback** ⚠️