1# Coding Standard for the ANGLE Project 2 3## Google Style Guide 4 5We generally use the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) as a basis for 6our Coding Standard, however we will deviate from it in a few areas, as noted 7below. 8 9Items marked {DEV} indicate a deviation from the Google guidelines. Items marked 10{DO} are reiterating points from the Google guidelines. 11 12Before you upload code to Gerrit, use `git cl format` to auto-format your code. 13This will catch most of the trivial formatting errors and save you time. 14 15### [Header Files](https://google.github.io/styleguide/cppguide.html#Header_Files) 16 17* We use **`.h`** for C++ headers. 18* {DEV} #define guards should be of the form: `<PATH>_<FILE>_H_`. (Compiler 19 codebase is varied, including `<PROJECT>_` makes the names excessively 20 long). 21 22### [Scoping](https://google.github.io/styleguide/cppguide.html#Scoping) 23 24* {DO} avoid globally scoped variables, unless absolutely necessary. 25 26### [Classes](https://google.github.io/styleguide/cppguide.html#Classes) 27 28* {DEV} Inherit (privately) from angle::NonCopyable helper class (defined in 29 common/angleutils.h) to disable default copy and assignment operators. 30 31### [Other C++ Features](https://google.github.io/styleguide/cppguide.html#Other_C++_Features) 32 33* {DEV} all parameters passed by reference, except for STL containers (e.g. 34 std::vector, std::list), must be labeled `const`. For return parameters 35 other than STL containers, use a pointer. 36* {DO} avoid use of default arguments. 37* {DONT} use C++ exceptions, they are disabled in the builds and not caught. 38* {DO} use nullptr (instead of 0 or NULL) for pointers. 39* {DO} use size\_t for loop iterators and size values. 40* {DO} use uint8\_t pointers instead of void pointers to denote binary data. 41* {DO} use C++11/14 according to the [Chromium c++ 11/14 guide] 42 (http://chromium-cpp.appspot.com/). 43 44### [Naming](https://google.github.io/styleguide/cppguide.html#Naming) 45 46#### File Names 47 48* {DEV} Filenames should be all lowercase and can include underscores (`_`). 49 If the file is an implementation of a class, the filename may be capitalized 50 the same as the major class. 51* {DEV} We use .cpp (instead of .cc), .h and .inl (inlined files) for C++ 52 files and headers. 53 54#### Directory Names 55* Directory names should be all lowercase, unless following an externally 56 imposed capitalization (eg include/EGL, or src/libGLESv2, etc) 57 58#### Variable Names 59 60Use the following guidelines, they do deviate somewhat from the [Google 61guidelines](https://google.github.io/styleguide/cppguide.html#Naming). 62 63* Class and type names: start with capital letter and use CamelCase. 64* {DEV} Class member variables: use an **`m`** prefix instead of trailing 65underscore and use CamelCase. 66* Global variables (if they must be used): use a **`g`** prefix. 67* {DEV} Variable names: start with lower case and use CamelCase (chosen for consistency) 68* {DEV} Function names: Member functions start with lower case and use CamelCase. Non-member and static member functions start with capital letter and 69use CamelCase (chosen for consistency) 70* {DO} Constants: start with a **`k`** and use CamelCase 71* Namespaces: short names. use all lower case 72* {DEV} Enum Names: use strongly typed class enums when possible. Use CamelCase for class enum members. See [official docs][EnumsOfficial]. 73* Macros: all uppercase with underscores 74* Exceptions to naming: use common sense! 75 76[EnumsOfficial]: https://google.github.io/styleguide/cppguide.html#Enumerator_Names 77 78### [Comments](https://google.github.io/styleguide/cppguide.html#Comments) 79 80* {DO} read and follow Google's recommendations. 81* Each file **must** start with the following boilerplate notice: 82 83``` 84// 85// Copyright $YEAR The ANGLE Project Authors. All rights reserved. 86// Use of this source code is governed by a BSD-style license that can be 87// found in the LICENSE file. 88// 89``` 90 91* $YEAR should be set to the current year at the time a file is created, and not changed thereafter. 92 93### [Formatting](https://google.github.io/styleguide/cppguide.html#Formatting) 94 95* {DEV} Avoid excessively long lines. Please keep lines under 100 columns 96 long. 97* Use unix-style newlines. 98* {DO} use only spaces. No tab characters. Configure your editor to emit 99 spaces when you hit the TAB-key. 100* {DEV} indent 4 spaces at a time. 101* conditionals: place space outside the parenthesis. No spaces inside. 102* switch statements: use the output of `git cl format`. 103* class format(eg private, public, protected): indent by 2 spaces. Regular 104 4-space indent from the outer scope for declarations/definitions. 105* pointers and references: **`*`** and **`&`** tight against the variable 106* namespaces: are not indented. 107* extern code blocks: are not indented. 108* {DEV} braces should go on a separate line, except for functions defined in a 109 header file where the whole function declaration and definition fit on one 110 line. 111 112Examples: 113 114``` 115if (conditional) 116{ 117 stuff(); 118} 119else 120{ 121 otherstuff() 122} 123``` 124 125``` 126switch (conditional) 127{ 128 case foo: 129 dostuff(); 130 break; 131 case bar: 132 otherstuff(); 133 break; 134 default: 135 WTFBBQ(); 136} 137``` 138 139``` 140class MyClass : public Foo 141{ 142 public: 143 MyClass(); 144 ~MyClass() {}; 145 private: 146 DISALLOW_COPY_AND_ASSIGN(MyClass); 147}; 148``` 149 150``` 151char *c; 152const string &str; 153``` 154 155### [Exceptions to the Rules](https://google.github.io/styleguide/cppguide.html#Exceptions_to_the_Rules) 156 157* If modifying pre-existing code that does not match the standard, the altered 158 portions of the code should be changed to match the standard. 159 160### Generated Source Files 161 162Prefer storing generated sources as baked files in the repository. Avoid using 163GN actions to run Python scripts. 164 165**Definition:** 166 167Sometimes helper scripts can create compilable sources more easily from XML or 168JSON data sources than maintaining source files by hand. These scripts are often 169written in Python and output generated sources. 170 171**Decision** 172 173Storing generated sources in the repository makes integration easier for non-GN 174users. Python scripts can be expensive and slow to run at compile-time. 175Generated sources can be a pain point for messing up builds. 176 177It could be possible to solve the build clobbering problem. And we could replace 178Python with something faster. But to allow for easier integration with our tools 179and customers we should bake generated files into the repository. 180