Coding Conventions

Dawn Coding Standard

Introduction

This document attempts to describe a few coding standards that are being used in the Dawn source tree. Although no coding standards should be regarded as absolute requirements to be followed in all instances, you should try to follow the LLVM coding standard. We deviate from the LLVM standard in certain areas as listed in the following.

Supported C++17 Language and Library Features

We do not impose any restrictions on C++17 features. The generated code however needs to be compliant to C++11. While we generally allow the usage of C++ exceptions, you should avoid them at the interface boundary to make exposing the API more convenient.

Style Issues

Naming of Types, Functions, Variables, and Enumerators

• Variable Names should start with a lower-case letter (e.g textFileReader) as opposed to LLVM which starts with an uppercase-letter.

• Members should start with a lower-case letter and contain an suffix (e.g myMember)

• Namespaces are all lower case and are in snake_case (e.g. dawn_generated)

• Template Typenames all start with an uppercase T, followed by an uppercase name (e.g. TValue, TWeight)

For types, functions and enumerators you should follow the LLVM style.

Source Code Formatting

These rules have been updated as of December 2019. All new code should conform to these rules. Old code can be adapted continuously if it is affected by a new task.

Minimal Code

Always favor minimal code. Do not introduce convenience functions without a good reason, e.g.

  class Foo {
    Foo(int, int, int);
    Foo(std::array<int, 3>);
  };

is bad. Delete one of the constructors.

Include Order

Includes should be placed in the following order

• Headers in the same folder

• Headers in the same library

• Other libraries

• std headers

For headers in the same folder, do not put the absolute path.

Miscellaneous Guidelines

• Do not define non-templated member functions which are longer than one line in header files (except for templated functions). E.g.

  class Foo {
    int i;
    int getI() { return i; }
  };

is ok. The following is not:

  class Bar {
    int computeI() {
      bool converged = false;
      while (!converged) {
        //some complicated algorithm
      }
    }
  };

• Do not use extern in free header functions since its redundant.

• Prefer #pragma once over include guards, since include guards need to be maintained if the header file is renamed and code or includes could accidentally be placed outside of the guards.

• Always use braces for if-else and loop bodies (also if they are one line). This helps to avoid bugs, for example if additional statements are appended to a loop or if-else clause at a later stage.

• virtual functions should specify exactly on of virtual, override and final, see also C++ Core Guidelines C.128

Clang Format

To enforce most of these coding standards, there is a clang-format file located in the root directory at <dawn-dir>/.clangformat. There is also a git pre-commit hook to ensure that all code commited is formatted according to the .clang-format file.