For other languages, please see the Chromium style guides.
Chromium follows the Google C++ Style Guide unless an exception is listed below.
A checkout should give you clang-format to automatically format C++ code. By policy, Clang's formatting of code should always be accepted in code reviews.
You can propose changes to this style guide by sending an email to cxx@chromium.org
. Ideally, the list will arrive at some consensus and you can request review for a change to this file. If there's no consensus, src/styleguide/c++/OWNERS
get to decide.
Blink code in third_party/blink
uses Blink style.
Google style targets C++17. Chromium targets C++14; C++17 support is not expected before mid-2021. Additionally, some features of supported C++ versions remain forbidden. The status of Chromium's C++ support is covered in more detail in Modern C++ use in Chromium.
ForTesting
is the conventional suffix although similar patterns, such as ForTest
, are also accepted. These suffixes are checked at presubmit time to ensure the functions are called only by test files.*
and &
by the type rather than the variable name.(foo == 0)
to (0 == foo)
.Items local to a .cc file should be wrapped in an unnamed namespace. While some such items are already file-scope by default in C++, not all are; also, shared objects on Linux builds export all symbols, so unnamed namespaces (which restrict these symbols to the compilation unit) improve function call cost and reduce the size of entry point tables.
Symbols can be exported (made visible outside of a shared library/DLL) by annotating with a <COMPONENT>_EXPORT
macro name (where <COMPONENT>
is the name of the component being built, e.g. BASE, NET, CONTENT, etc.). Class annotations should precede the class name:
class FOO_EXPORT Foo { void Bar(); void Baz(); // ... };
Function annotations should precede the return type:
class FooSingleton { FOO_EXPORT Foo& GetFoo(); FOO_EXPORT Foo& SetFooForTesting(Foo* foo); void SetFoo(Foo* foo); // Not exported. };
Multiple inheritance and virtual inheritance are permitted in Chromium code, but discouraged (beyond the “interface” style of inheritance allowed by the Google style guide, for which we do not require classes to have the “Interface” suffix). Consider whether composition could solve the problem instead.
Simple accessors should generally be the only inline functions. These should be named using snake_case()
. Virtual functions should never be declared this way.
Remove most logging calls before checking in. Unless you're adding temporary logging to track down a specific bug, and you have a plan for how to collect the logged data from user machines, you should generally not add logging statements.
For the rare case when logging needs to stay in the codebase for a while, prefer DVLOG(1)
to other logging methods. This avoids bloating the release executable and in debug can be selectively enabled at runtime by command-line arguments:
--v=n
sets the global log level to n (default 0). All log statements with a log level less than or equal to the global level will be printed.--vmodule=mod=n[,mod=n,...]
overrides the global log level for the module mod. Supplying the string foo for mod will affect all files named foo.cc, while supplying a wildcard like *bar/baz*
will affect all files with bar/baz
in their full pathnames.To #ifdef
code for specific platforms, use the macros defined in build/build_config.h
and in the Chromium build config files, not other macros set by specific compilers or build environments (e.g. WIN32
).
Place platform-specific #includes in their own section below the “normal” #includes
. Repeat the standard #include
order within this section:
#include "foo/foo.h" #include <stdint.h> #include <algorithm> #include "base/strings/utf_string_conversions.h" #include "chrome/common/render_messages.h" #if defined(OS_WIN) #include <windows.h> #include "base/win/com_init_util.h" #elif defined(OS_POSIX) #include "base/posix/global_descriptors.h" #endif
size_t
for object and allocation sizes, object counts, array and pointer offsets, vector indices, and so on. This prevents casts when dealing with STL APIs, and if followed consistently across the codebase, minimizes casts elsewhere.size_t
for one of these concepts, e.g. as a storage space optimization. In these cases, continue to use size_t
in public-facing function declarations, and continue to use unsigned types internally (e.g. uint32_t
).checked_cast<T>
(from base/numerics/safe_conversions.h
) when you need to CHECK
that the source value is in range for the destination type. Use saturated_cast<T>
if you instead wish to clamp out-of-range values. CheckedNumeric
is an ergonomic way to perform safe arithmetic and casting in many cases.int
and size_t
. However, to the greatest degree possible, avoid letting these sized types bleed through the APIs of the layers in question.std::wstring
. Use base::string16
or base::FilePath
instead. (Windows-specific code interfacing with system APIs using wstring
and wchar_t
can still use string16
and char16
; it is safe to assume that these are equivalent to the “wide” types.)When functions need to take raw or smart pointers as parameters, use the following conventions. Here we refer to the parameter type as T
and name as t
.
t
's ownership, declare the param as T*
. The caller is expected to ensure t
stays alive as long as necessary, generally through the duration of the call. Exception: In rare cases (e.g. using lambdas with STL algorithms over containers of unique_ptr<>
s), you may be forced to declare the param as const std::unique_ptr<T>&
. Do this only when required.std::unique_ptr<T>
.scoped_refptr<T>
. The caller can decide whether it wishes to transfer ownership (by calling std::move(t)
when passing t
) or retain its ref (by simply passing t directly).Conventions for return values are similar with an important distinction:
std::unique_ptr<T>
or scoped_refptr<T>
by value when the impl is handing off ownership.const scoped_refptr<T>&
when the impl retains ownership so the caller isn‘t required to take a ref: this avoids bumping the reference count if the caller doesn’t need ownership and also helps binary size).A great deal of Chromium code predates the above rules. In particular, some functions take ownership of params passed as T*
, or take const scoped_refptr<T>&
instead of T*
, or return T*
instead of scoped_refptr<T>
(to avoid refcount churn pre-C++11). Try to clean up such code when you find it, or at least not make such usage any more widespread.
Unlike the Google style guide, Chromium style prefers forward declarations to #includes
where possible. This can reduce compile times and result in fewer files needing recompilation when a header changes.
You can and should use forward declarations for most types passed or returned by value, reference, or pointer, or types stored as pointer members or in most STL containers. However, if it would otherwise make sense to use a type as a member by-value, don't convert it to a pointer just to be able to forward-declare the type.
All files in Chromium start with a common license header. That header should look like this:
// Copyright $YEAR The Chromium Authors. All rights reserved. // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file.
Some important notes about this header:
(c)
after Copyright
.$YEAR
should be set to the current year at the time a file is created, and not changed thereafter.Use standard #include
guards in all header files (see the Google style guide sections on these for the naming convention). Do not use #pragma once
; historically it was not supported on all platforms, and it does not seem to outperform #include guards even on platforms which do support it.
The CHECK()
macro will cause an immediate crash if its condition is not met. DCHECK()
is like CHECK()
but is only compiled in when DCHECK_IS_ON
is true (debug builds and some bot configurations, but not end-user builds). NOTREACHED()
is equivalent to DCHECK(false)
. Here are some rules for using these:
DCHECK()
or NOTREACHED()
as assertions, e.g. to document pre- and post-conditions. A DCHECK()
means “this condition must always be true”, not “this condition is normally true, but perhaps not in exceptional cases.” Things like disk corruption or strange network errors are examples of exceptional circumstances that nevertheless should not result in DCHECK()
failure.DCHECK()
failure is a statement that the DCHECK()
can fail, which contradicts the point of writing the DCHECK()
. In particular, do not write code like the following:DCHECK(foo); if (!foo) // Eliminate this code. ... if (!bar) { // Replace this whole conditional with "DCHECK(bar);". NOTREACHED(); return; }
CHECK()
if the consequence of a failed assertion would be a security vulnerability, where crashing the browser is preferable. Because this takes down the whole browser, sometimes there are better options than CHECK()
. For example, if a renderer sends the browser process a malformed IPC, an attacker may control the renderer, but we can simply kill the offending renderer instead of crashing the whole browser.CHECK()
instead of DCHECK()
when trying to force crashes in release builds to sniff out which of your assertions is failing. Don‘t leave these in the codebase forever; remove them or change them back once you’ve solved the problem.ASSERT_xx()
and EXPECT_xx()
family of macros, which report failures gracefully and can continue running other tests.