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