This document sets out some light style requirements for contributing to QAT. In case you do not feel like reading this style guide, just run
trunk check
from the root directory before making a pull request. This script enforces all requirements described below programmatically. You can then refer to this guide for an explanation for why and how.
In case you have formatting issues, the manage script do the majority of the formatting foryou. If your toolchain on your local machine is set up correctly, you can simply run
./manage stylecheck --fix-issues
to automatically format all source files in compliance with the styles chosen for this project. To avoid different versions of the tool chain creating different formats or complaining about different static issues, we have created a docker image to serve as "the source of truth". In case your toolchain differ, you can use the provided docker image, just running:
make format-in-docker
This will mount your local source directory and perform formatting of the code. Likewise, if you need to run CI in the docker image, you can run:
make linux-ci
which will execute ./manage runci
inside the docker image.
Consistency and readability such that it is easy to read and understand code
that was not written by yourself. For example, if one developer uses CamelCase
for namespaces and snake_case
for classes while another uses snake_case
for
namespaces and CamelCase
you may end up with code sections that looks like
this
int32_t main()
{
name_space1::Class1 hello;
NameSpace2::class_name world;
}
which is hard to read.
The style guide applies to any new code written as well as code that is being
refactored added to the Passes
library. We do not rewrite existing code for
the sake just changing the style.
In case of a discrepancy between this guideline and clang-tidy
or
clang-format
, Clang tools rule. In case of discrepancy between this guide and
any guides subsequently referenced guides, this guide rules. However, feel free
to suggest changes. Changes will be incorporated on the basis that updated
styles are apply to new code and not existing code.
Naming is taken from the Microsoft AirSim project.
Code Element | Style | Comment |
---|---|---|
Namespace | snake_case | Differentiates namespace::ClassName and ClassName::SubClass names |
Class name | CamelCase | To differentiate from STL types which ISO recommends (do not use "C" or "T" prefixes) |
Type aliases | CamelCase | To differentiate from STL types which ISO recommends |
Template type parameters | CamelCase | To differentiate from STL types which ISO recommends |
Function name | camelCase | Lower case start is almost universal except for .NET world |
Parameters/Locals | snake_case | Vast majority of standards recommends this because _ is more readable to C++ crowd (although not much to Java/.NET crowd) |
Member variables | snake_case_with_ | The prefix _ is heavily discouraged as ISO has rules around reserving _identifiers, so we recommend suffix instead |
Enums and its members | CamelCase | Most except very old standards agree with this one |
Globals | g_snake_case | Avoid using globals whenever possible, but if you have to use g_ . |
Constants | UPPER_CASE | Very contentious and we just have to pick one here, unless if is a private constant in class or method, then use naming for Members or Locals |
File names | Match case of class name in file | Lot of pro and cons either way but this removes inconsistency in auto generated code (important for ROS) |
In general, modernize the code where possible. For instance, prefer using
over
typedef
.
Prefer #pragma once
over #ifdef
protection.
trunk check
(...)
Passes/src/OpsCounter/OpsCounter.cpp:39:21: error: missing username/bug in TODO [google-readability-todo,-warnings-as-errors]
// TODO: Fails to load if this is present
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// TODO(tfr): Fails to load if this is present
Copyright headers are comments of the form
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.
For header files, prefer to put #prama once
before the copyright.
We indent with 2 spaces. Nested namespaces are not indented.