# C++ style guide

The Fuchsia project follows the public [Google C++ style guide][google-guide], with a
few exceptions.

Using [clang-format][clang-format] is a good practice as it ensures your code is in
compliance with the style guide. Tricium checks in Gerrit also use clang-format as a
non-gating linter. However, you may still manually format code as long as it complies
with these guidelines.

#### Tip: TODO comments

When following the Google C++ style guide by entering a bug number in a TODO
comment, using the form `TODO(fxbug.dev/11111)` will provide an address that
can be used as a URL.

### Exceptions

#### Line length

Fuchsia uses 100 columns instead of 80.

#### Braces

Always use braces `{ }` when the contents of a block are more than one line.
This is something you need to watch since Clang-format doesn't know to add
these.

```cpp
// Don't do this.
while (!done)
  doSomethingWithAReallyLongLine(
       wrapped_arg);

// Correct.
while (!done) {
  doSomethingWithAReallyLongLine(
       wrapped_arg);
}
```


#### Conditionals and loops

Do not use spaces inside parentheses (the Google style guide discourages but
permits this).

Do not use the single-line form for short conditionals and loops (the Google
style guide permits both forms):

```cpp
// Don't do this:
if (x == kFoo) return new Foo();

// Correct.
if (x == kFoo)
  return new Foo;
```

#### Namespace names

* Nested namespaces are forbidden, with the following exceptions:
  - `internal` (when required to hide implementation details of templated code)
  - code generated by the FIDL compiler
* The following top-level namespaces are forbidden:
  - `internal`
  - `fuchsia` (except in code generated by the FIDL compiler)
* Namespaces in IDK libraries must be kept to as short a list as possible.
  A later document will provide an explicit list of allowed namespaces; in the
  meantime, new namespaces should be introduced thoughtfully.
* Namespaces in non-IDK libraries should also be chosen so as to reduce the risk
  of clashes. Very generic nouns (eg. `media`) are best avoided.

Rationale: [Tip of the Week #130: Namespace Naming][totw-130]

[clang-format]: https://clang.llvm.org/docs/ClangFormat.html
[google-guide]: https://google.github.io/styleguide/cppguide.html
[totw-130]: https://abseil.io/tips/130

#### Includes

* If the header being included is a system, global, or library header (see
  [Naming C/C++ objects](naming.md) for precise definitions), use
  `<angle brackets>` and the complete name of the header. These headers are
  considered "C library headers" for the purposes of the Google C++ Style
  Guide:

  ```cpp
  #include <zircon/syscalls.h>           // System header
  #include <fuchsia/io/cpp/fidl.h>       // Global header
  #include <lib/fdio/fd.h>               // Library header
  ```

* If the header being included is a implementation header, use `"quotes"` and
  use the full path to the header from the root of the source tree. These
  headers are considered "your project's headers" for the purposes of the
  Google C++ Style Guide:

  ```cpp
  #include "src/ui/scenic/bin/app.h"     // Implementation header
  ```

* Third-party headers can be included using the root-relative path (e.g.
  `#include "third_party/skia/include/core/SkPaint.h"`) or using their canonical header
  names (e.g. `#include <gtest/gtest.h>`).