1# C++ Style Guide for google-cloud-cpp 2 3This project follows the [Google Style Guide][google-style-guide-link] 4(hereafter GSG). In a few cases where the GSG gives latitude, we have made a 5choice for consistency within this project. The following describes where we 6differ from the GSG. 7 8[google-style-guide-link]: https://google.github.io/styleguide/cppguide.html 9 10## Include Guards 11 12All header files should have include guards formatted like 13`PROJECT_DIR_FILE_H`. This differs from the advice in the GSG in that ours do 14not end with a trailing underscore. 15 16[link to GSG's section on include guards](https://google.github.io/styleguide/cppguide.html#The__define_Guard) 17 18## Where to put `const` 19 20Put the const on the right of what it modifies, as in `std::string const&`. 21This simplifies the rules for const making it *always* modify what is on its 22left. This is sometimes referred to as ["east const"][east-const-link]. 23 24[link to GSG's section on using const](https://google.github.io/styleguide/cppguide.html#Use_of_const) 25 26[east-const-link]: https://google.com/search?q=c%2B%2B+"east+const" 27 28## Pointer and Reference Expressions 29 30Place the asterisk or ampersand adjacent to the type when declaring pointers or 31references. 32 33```C++ 34char* c; // GOOD 35std::string const& str; // GOOD 36 37char *c; // BAD 38string const &str; // BAD 39string const & str; // BAD 40``` 41 42[link to GSG's section on pointer and reference expressions](https://google.github.io/styleguide/cppguide.html#Pointer_and_Reference_Expressions) 43 44## Order of Includes 45 46Order includes from local to global to minimize implicit dependencies between 47headers. That is, start with the `.h` file that corresponds to the current 48`.cc` file (also do this for the corresponding unit test file), followed by 49other `.h` files from the same project, followed by includes from external 50projects, followed by C++ standard library headers, followed by C system 51headers. For example: 52 53```C++ 54// Within the file google/cloud/x/foo.cc 55#include "google/cloud/x/foo.h" 56#include "google/cloud/x/bar.h" 57#include "google/cloud/y/baz.h" 58#include <grpcpp/blorg.h> 59#include <google/bigtable/blah.h> 60#include <map> 61#include <vector> 62#include <unistd.h> 63``` 64 65This differs substantially from the corresponding section in the GSG, but we 66feel the rule presented here is both simpler and better minimizes the implicit 67dependencies exposed to each header. 68 69[link to GSG's section on include order](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes) 70 71## Legal Notice and Author Line 72 73Every file should contain license boilerplate, for new files use: 74 75```C++ 76// Copyright YYYY Google LLC 77// 78// Licensed under the Apache License, Version 2.0 (the "License"); 79// you may not use this file except in compliance with the License. 80// You may obtain a copy of the License at 81// 82// http://www.apache.org/licenses/LICENSE-2.0 83// 84// Unless required by applicable law or agreed to in writing, software 85// distributed under the License is distributed on an "AS IS" BASIS, 86// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 87// See the License for the specific language governing permissions and 88// limitations under the License. 89``` 90 91where `YYYY` is the year when the file is being introduced. Do not change existing files boilerplate. 92 93## Doxygen Comments 94 95Use Doxygen-style comments to document classes, functions, etc. Prefer 96`@directives` over `\directives`. Do document the template parameters for 97template classes. Use `///` for one-line Doxygen comments, use `/** */` 98otherwise. Document all classes, functions, and symbols exposed as part of the 99API of the library, even obvious ones. 100 101## TODO Comments 102 103Use `TODO` comments for code that is temporary, a short-term solution, or 104good-enough but not perfect. All TODO comments should reference a github issue 105and a brief description: 106 107``` 108// TODO(#123) - here we need to randomize the sleep delay…. 109``` 110