General Code Guidelines

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