Blame - cppguide.html - platform/external/google-styleguide

blob: eb0fe64a13a126b029904da5a141814d918a3f39 [file] [log] [blame]

Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1	<!DOCTYPE html>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	2	<html lang="en">
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3	<head>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4	<meta charset="utf-8">
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5	<title>Google C++ Style Guide</title>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	6	<link rel="stylesheet" href="include/styleguide.css">
				7	<script src="include/styleguide.js"></script>
				8	<link rel="shortcut icon" href="https://www.google.com/favicon.ico">
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	9	</head>
				10	<body onload="initStyleGuide();">
				11	<div id="content">
				12	<h1>Google C++ Style Guide</h1>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	13	<div class="main_body">
				14
				15	<h2 class="ignoreLink" id="Background">Background</h2>
				16
				17	<p>C++ is one of the main development languages used by
				18	many of Google's open-source projects. As every C++
				19	programmer knows, the language has many powerful features, but
				20	this power brings with it complexity, which in turn can make
				21	code more bug-prone and harder to read and maintain.</p>
				22
				23	<p>The goal of this guide is to manage this complexity by
				24	describing in detail the dos and don'ts of writing C++ code.
				25	These rules exist to
				26	keep the code base manageable while still allowing
				27	coders to use C++ language features productively.</p>
				28
				29	<p><em>Style</em>, also known as readability, is what we call
				30	the conventions that govern our C++ code. The term Style is a
				31	bit of a misnomer, since these conventions cover far more than
				32	just source file formatting.</p>
				33
				34	<p>
				35	Most open-source projects developed by
				36	Google conform to the requirements in this guide.
				37	</p>
				38
				39
				40
				41
				42
				43	<p>Note that this guide is not a C++ tutorial: we assume that
				44	the reader is familiar with the language. </p>
				45
				46	<h3 id="Goals">Goals of the Style Guide</h3>
				47	<div class="stylebody">
				48	<p>Why do we have this document?</p>
				49
				50	<p>There are a few core goals that we believe this guide should
				51	serve. These are the fundamental <b>why</b>s that
				52	underlie all of the individual rules. By bringing these ideas to
				53	the fore, we hope to ground discussions and make it clearer to our
				54	broader community why the rules are in place and why particular
				55	decisions have been made. If you understand what goals each rule is
				56	serving, it should be clearer to everyone when a rule may be waived
				57	(some can be), and what sort of argument or alternative would be
				58	necessary to change a rule in the guide.</p>
				59
				60	<p>The goals of the style guide as we currently see them are as follows:</p>
				61	<dl>
				62	<dt>Style rules should pull their weight</dt>
				63	<dd>The benefit of a style rule
				64	must be large enough to justify asking all of our engineers to
				65	remember it. The benefit is measured relative to the codebase we would
				66	get without the rule, so a rule against a very harmful practice may
				67	still have a small benefit if people are unlikely to do it
				68	anyway. This principle mostly explains the rules we don’t have, rather
				69	than the rules we do: for example, <code>goto</code> contravenes many
				70	of the following principles, but is already vanishingly rare, so the Style
				71	Guide doesn’t discuss it.</dd>
				72
				73	<dt>Optimize for the reader, not the writer</dt>
				74	<dd>Our codebase (and most individual components submitted to it) is
				75	expected to continue for quite some time. As a result, more time will
				76	be spent reading most of our code than writing it. We explicitly
				77	choose to optimize for the experience of our average software engineer
				78	reading, maintaining, and debugging code in our codebase rather than
				79	ease when writing said code. "Leave a trace for the reader" is a
				80	particularly common sub-point of this principle: When something
				81	surprising or unusual is happening in a snippet of code (for example,
				82	transfer of pointer ownership), leaving textual hints for the reader
				83	at the point of use is valuable (<code>std::unique_ptr</code>
				84	demonstrates the ownership transfer unambiguously at the call
				85	site). </dd>
				86
				87	<dt>Be consistent with existing code</dt>
				88	<dd>Using one style consistently through our codebase lets us focus on
				89	other (more important) issues. Consistency also allows for
				90	automation: tools that format your code or adjust
				91	your <code>#include</code>s only work properly when your code is
				92	consistent with the expectations of the tooling. In many cases, rules
				93	that are attributed to "Be Consistent" boil down to "Just pick one and
				94	stop worrying about it"; the potential value of allowing flexibility
				95	on these points is outweighed by the cost of having people argue over
				96	them. </dd>
				97
				98	<dt>Be consistent with the broader C++ community when appropriate</dt>
				99	<dd>Consistency with the way other organizations use C++ has value for
				100	the same reasons as consistency within our code base. If a feature in
				101	the C++ standard solves a problem, or if some idiom is widely known
				102	and accepted, that's an argument for using it. However, sometimes
				103	standard features and idioms are flawed, or were just designed without
				104	our codebase's needs in mind. In those cases (as described below) it's
				105	appropriate to constrain or ban standard features. In some cases we
				106	prefer a homegrown or third-party library over a library defined in
				107	the C++ Standard, either out of perceived superiority or insufficient
				108	value to transition the codebase to the standard interface.</dd>
				109
				110	<dt>Avoid surprising or dangerous constructs</dt>
				111	<dd>C++ has features that are more surprising or dangerous than one
				112	might think at a glance. Some style guide restrictions are in place to
				113	prevent falling into these pitfalls. There is a high bar for style
				114	guide waivers on such restrictions, because waiving such rules often
				115	directly risks compromising program correctness.
				116	</dd>
				117
				118	<dt>Avoid constructs that our average C++ programmer would find tricky
				119	or hard to maintain</dt>
				120	<dd>C++ has features that may not be generally appropriate because of
				121	the complexity they introduce to the code. In widely used
				122	code, it may be more acceptable to use
				123	trickier language constructs, because any benefits of more complex
				124	implementation are multiplied widely by usage, and the cost in understanding
				125	the complexity does not need to be paid again when working with new
				126	portions of the codebase. When in doubt, waivers to rules of this type
				127	can be sought by asking
				128	your project leads. This is specifically
				129	important for our codebase because code ownership and team membership
				130	changes over time: even if everyone that works with some piece of code
				131	currently understands it, such understanding is not guaranteed to hold a
				132	few years from now.</dd>
				133
				134	<dt>Be mindful of our scale</dt>
				135	<dd>With a codebase of 100+ million lines and thousands of engineers,
				136	some mistakes and simplifications for one engineer can become costly
				137	for many. For instance it's particularly important to
				138	avoid polluting the global namespace: name collisions across a
				139	codebase of hundreds of millions of lines are difficult to work with
				140	and hard to avoid if everyone puts things into the global
				141	namespace.</dd>
				142
				143	<dt>Concede to optimization when necessary</dt>
				144	<dd>Performance optimizations can sometimes be necessary and
				145	appropriate, even when they conflict with the other principles of this
				146	document.</dd>
				147	</dl>
				148
				149	<p>The intent of this document is to provide maximal guidance with
				150	reasonable restriction. As always, common sense and good taste should
				151	prevail. By this we specifically refer to the established conventions
				152	of the entire Google C++ community, not just your personal preferences
				153	or those of your team. Be skeptical about and reluctant to use
				154	clever or unusual constructs: the absence of a prohibition is not the
				155	same as a license to proceed. Use your judgment, and if you are
				156	unsure, please don't hesitate to ask your project leads to get additional
				157	input.</p>
				158
				159	</div>
				160
				161
				162
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	163	<h2 id="C++_Version">C++ Version</h2>
				164
				165	<p>
				166	Currently, code should target C++11, i.e., should not use C++14 or
				167	C++17 features. The C++ version targeted by this guide will advance
				168	(aggressively) over time.</p>
				169
				170	<p>
				171	Code should avoid features that have been removed from
				172	the latest language version (currently C++17), as well as the rare
				173	cases where code has a different meaning in that latest version.
				174	Use of some C++ features is restricted or disallowed. Do not use
				175	<a href="#Nonstandard_Extensions">non-standard extensions</a>.</p>
				176
				177
				178
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	179	<h2 id="Header_Files">Header Files</h2>
				180
				181	<p>In general, every <code>.cc</code> file should have an
				182	associated <code>.h</code> file. There are some common
				183	exceptions, such as unittests and
				184	small <code>.cc</code> files containing just a
				185	<code>main()</code> function.</p>
				186
				187	<p>Correct use of header files can make a huge difference to
				188	the readability, size and performance of your code.</p>
				189
				190	<p>The following rules will guide you through the various
				191	pitfalls of using header files.</p>
				192
				193	<a id="The_-inl.h_Files"></a>
				194	<h3 id="Self_contained_Headers">Self-contained Headers</h3>
				195
				196	<div class="summary">
				197	<p>Header files should be self-contained (compile on their own) and
				198	end in <code>.h</code>. Non-header files that are meant for inclusion
				199	should end in <code>.inc</code> and be used sparingly.</p>
				200	</div>
				201
				202	<div class="stylebody">
				203	<p>All header files should be self-contained. Users and refactoring
				204	tools should not have to adhere to special conditions to include the
				205	header. Specifically, a header should
				206	have <a href="#The__define_Guard">header guards</a> and include all
				207	other headers it needs.</p>
				208
				209	<p>Prefer placing the definitions for template and inline functions in
				210	the same file as their declarations. The definitions of these
				211	constructs must be included into every <code>.cc</code> file that uses
				212	them, or the program may fail to link in some build configurations. If
				213	declarations and definitions are in different files, including the
				214	former should transitively include the latter. Do not move these
				215	definitions to separately included header files (<code>-inl.h</code>);
				216	this practice was common in the past, but is no longer allowed.</p>
				217
				218	<p>As an exception, a template that is explicitly instantiated for
				219	all relevant sets of template arguments, or that is a private
				220	implementation detail of a class, is allowed to be defined in the one
				221	and only <code>.cc</code> file that instantiates the template.</p>
				222
				223	<p>There are rare cases where a file designed to be included is not
				224	self-contained. These are typically intended to be included at unusual
				225	locations, such as the middle of another file. They might not
				226	use <a href="#The__define_Guard">header guards</a>, and might not include
				227	their prerequisites. Name such files with the <code>.inc</code>
				228	extension. Use sparingly, and prefer self-contained headers when
				229	possible.</p>
				230
				231	</div>
				232
				233	<h3 id="The__define_Guard">The #define Guard</h3>
				234
				235	<div class="summary">
				236	<p>All header files should have <code>#define</code> guards to
				237	prevent multiple inclusion. The format of the symbol name
				238	should be
				239	<code><i><PROJECT></i>_<i><PATH></i>_<i><FILE></i>_H_</code>.</p>
				240	</div>
				241
				242	<div class="stylebody">
				243
				244
				245
				246	<p>To guarantee uniqueness, they should
				247	be based on the full path in a project's source tree. For
				248	example, the file <code>foo/src/bar/baz.h</code> in
				249	project <code>foo</code> should have the following
				250	guard:</p>
				251
				252	<pre>#ifndef FOO_BAR_BAZ_H_
				253	#define FOO_BAR_BAZ_H_
				254
				255	...
				256
				257	#endif // FOO_BAR_BAZ_H_
				258	</pre>
				259
				260
				261
				262
				263	</div>
				264
				265	<h3 id="Forward_Declarations">Forward Declarations</h3>
				266
				267	<div class="summary">
				268	<p>Avoid using forward declarations where possible.
				269	Just <code>#include</code> the headers you need.</p>
				270	</div>
				271
				272	<div class="stylebody">
				273
				274	<div class="definition">
				275	<p>A "forward declaration" is a declaration of a class,
				276	function, or template without an associated definition.</p>
				277	</div>
				278
				279	<div class="pros">
				280	<ul>
				281	<li>Forward declarations can save compile time, as
				282	<code>#include</code>s force the compiler to open
				283	more files and process more input.</li>
				284
				285	<li>Forward declarations can save on unnecessary
				286	recompilation. <code>#include</code>s can force
				287	your code to be recompiled more often, due to unrelated
				288	changes in the header.</li>
				289	</ul>
				290	</div>
				291
				292	<div class="cons">
				293	<ul>
				294	<li>Forward declarations can hide a dependency, allowing
				295	user code to skip necessary recompilation when headers
				296	change.</li>
				297
				298	<li>A forward declaration may be broken by subsequent
				299	changes to the library. Forward declarations of functions
				300	and templates can prevent the header owners from making
				301	otherwise-compatible changes to their APIs, such as
				302	widening a parameter type, adding a template parameter
				303	with a default value, or migrating to a new namespace.</li>
				304
				305	<li>Forward declaring symbols from namespace
				306	<code>std::</code> yields undefined behavior.</li>
				307
				308	<li>It can be difficult to determine whether a forward
				309	declaration or a full <code>#include</code> is needed.
				310	Replacing an <code>#include</code> with a forward
				311	declaration can silently change the meaning of
				312	code:
				313	<pre> // b.h:
				314	struct B {};
				315	struct D : B {};
				316
				317	// good_user.cc:
				318	#include "b.h"
				319	void f(B*);
				320	void f(void*);
				321	void test(D* x) { f(x); } // calls f(B*)
				322	</pre>
				323	If the <code>#include</code> was replaced with forward
				324	decls for <code>B</code> and <code>D</code>,
				325	<code>test()</code> would call <code>f(void*)</code>.
				326	</li>
				327
				328	<li>Forward declaring multiple symbols from a header
				329	can be more verbose than simply
				330	<code>#include</code>ing the header.</li>
				331
				332	<li>Structuring code to enable forward declarations
				333	(e.g. using pointer members instead of object members)
				334	can make the code slower and more complex.</li>
				335
				336
				337	</ul>
				338	</div>
				339
				340	<div class="decision">
				341	<ul>
				342	<li>Try to avoid forward declarations of entities
				343	defined in another project.</li>
				344
				345	<li>When using a function declared in a header file,
				346	always <code>#include</code> that header.</li>
				347
				348	<li>When using a class template, prefer to
				349	<code>#include</code> its header file.</li>
				350	</ul>
				351
				352	<p>Please see <a href="#Names_and_Order_of_Includes">Names and Order
				353	of Includes</a> for rules about when to #include a header.</p>
				354	</div>
				355
				356	</div>
				357
				358	<h3 id="Inline_Functions">Inline Functions</h3>
				359
				360	<div class="summary">
				361	<p>Define functions inline only when they are small, say, 10
				362	lines or fewer.</p>
				363	</div>
				364
				365	<div class="stylebody">
				366
				367	<div class="definition">
				368	<p>You can declare functions in a way that allows the compiler to expand
				369	them inline rather than calling them through the usual
				370	function call mechanism.</p>
				371	</div>
				372
				373	<div class="pros">
				374	<p>Inlining a function can generate more efficient object
				375	code, as long as the inlined function is small. Feel free
				376	to inline accessors and mutators, and other short,
				377	performance-critical functions.</p>
				378	</div>
				379
				380	<div class="cons">
				381	<p>Overuse of inlining can actually make programs slower.
				382	Depending on a function's size, inlining it can cause the
				383	code size to increase or decrease. Inlining a very small
				384	accessor function will usually decrease code size while
				385	inlining a very large function can dramatically increase
				386	code size. On modern processors smaller code usually runs
				387	faster due to better use of the instruction cache.</p>
				388	</div>
				389
				390	<div class="decision">
				391	<p>A decent rule of thumb is to not inline a function if
				392	it is more than 10 lines long. Beware of destructors,
				393	which are often longer than they appear because of
				394	implicit member- and base-destructor calls!</p>
				395
				396	<p>Another useful rule of thumb: it's typically not cost
				397	effective to inline functions with loops or switch
				398	statements (unless, in the common case, the loop or
				399	switch statement is never executed).</p>
				400
				401	<p>It is important to know that functions are not always
				402	inlined even if they are declared as such; for example,
				403	virtual and recursive functions are not normally inlined.
				404	Usually recursive functions should not be inline. The
				405	main reason for making a virtual function inline is to
				406	place its definition in the class, either for convenience
				407	or to document its behavior, e.g., for accessors and
				408	mutators.</p>
				409	</div>
				410
				411	</div>
				412
				413	<h3 id="Names_and_Order_of_Includes">Names and Order of Includes</h3>
				414
				415	<div class="summary">
				416	<p>Use standard order for readability and to avoid hidden
				417	dependencies: Related header, C library, C++ library, other libraries'
				418	<code>.h</code>, your project's <code>.h</code>.</p>
				419	</div>
				420
				421	<div class="stylebody">
				422	<p>
				423	All of a project's header files should be
				424	listed as descendants of the project's source
				425	directory without use of UNIX directory shortcuts
				426	<code>.</code> (the current directory) or <code>..</code>
				427	(the parent directory). For example,
				428
				429	<code>google-awesome-project/src/base/logging.h</code>
				430	should be included as:</p>
				431
				432	<pre>#include "base/logging.h"
				433	</pre>
				434
				435	<p>In <code><var>dir/foo</var>.cc</code> or
				436	<code><var>dir/foo_test</var>.cc</code>, whose main
				437	purpose is to implement or test the stuff in
				438	<code><var>dir2/foo2</var>.h</code>, order your includes
				439	as follows:</p>
				440
				441	<ol>
				442	<li><code><var>dir2/foo2</var>.h</code>.</li>
				443
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	444	<li>A blank line</li>
				445
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	446	<li>C system files.</li>
				447
				448	<li>C++ system files.</li>
				449
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	450	<li>A blank line</li>
				451
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	452	<li>Other libraries' <code>.h</code>
				453	files.</li>
				454
				455	<li>
				456	Your project's <code>.h</code>
				457	files.</li>
				458	</ol>
				459
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	460	<p>Note that any adjacent blank lines should be collapsed.</p>
				461
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	462	<p>With the preferred ordering, if
				463	<code><var>dir2/foo2</var>.h</code> omits any necessary
				464	includes, the build of <code><var>dir/foo</var>.cc</code>
				465	or <code><var>dir/foo</var>_test.cc</code> will break.
				466	Thus, this rule ensures that build breaks show up first
				467	for the people working on these files, not for innocent
				468	people in other packages.</p>
				469
				470	<p><code><var>dir/foo</var>.cc</code> and
				471	<code><var>dir2/foo2</var>.h</code> are usually in the same
				472	directory (e.g. <code>base/basictypes_test.cc</code> and
				473	<code>base/basictypes.h</code>), but may sometimes be in different
				474	directories too.</p>
				475
				476
				477
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	478	<p>Note that the C compatibility headers such as <code>stddef.h</code>
				479	are essentially interchangeable with their C++ counterparts
				480	(<code>cstddef</code>)
				481	Either style is acceptable, but prefer consistency with existing code.</p>
				482
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	483	<p>Within each section the includes should be ordered
				484	alphabetically. Note that older code might not conform to
				485	this rule and should be fixed when convenient.</p>
				486
				487	<p>You should include all the headers that define the symbols you rely
				488	upon, except in the unusual case of <a href="#Forward_Declarations">forward
				489	declaration</a>. If you rely on symbols from <code>bar.h</code>,
				490	don't count on the fact that you included <code>foo.h</code> which
				491	(currently) includes <code>bar.h</code>: include <code>bar.h</code>
				492	yourself, unless <code>foo.h</code> explicitly demonstrates its intent
				493	to provide you the symbols of <code>bar.h</code>. However, any
				494	includes present in the related header do not need to be included
				495	again in the related <code>cc</code> (i.e., <code>foo.cc</code> can
				496	rely on <code>foo.h</code>'s includes).</p>
				497
				498	<p>For example, the includes in
				499
				500	<code>google-awesome-project/src/foo/internal/fooserver.cc</code>
				501	might look like this:</p>
				502
				503
				504	<pre>#include "foo/server/fooserver.h"
				505
				506	#include <sys/types.h>
				507	#include <unistd.h>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	508	#include <vector>
				509
				510	#include "base/basictypes.h"
				511	#include "base/commandlineflags.h"
				512	#include "foo/server/bar.h"
				513	</pre>
				514
				515	<p class="exception">Sometimes, system-specific code needs
				516	conditional includes. Such code can put conditional
				517	includes after other includes. Of course, keep your
				518	system-specific code small and localized. Example:</p>
				519
				520	<pre>#include "foo/public/fooserver.h"
				521
				522	#include "base/port.h" // For LANG_CXX11.
				523
				524	#ifdef LANG_CXX11
				525	#include <initializer_list>
				526	#endif // LANG_CXX11
				527	</pre>
				528
				529	</div>
				530
				531	<h2 id="Scoping">Scoping</h2>
				532
				533	<h3 id="Namespaces">Namespaces</h3>
				534
				535	<div class="summary">
				536	<p>With few exceptions, place code in a namespace. Namespaces
				537	should have unique names based on the project name, and possibly
				538	its path. Do not use <i>using-directives</i> (e.g.
				539	<code>using namespace foo</code>). Do not use
				540	inline namespaces. For unnamed namespaces, see
				541	<a href="#Unnamed_Namespaces_and_Static_Variables">Unnamed Namespaces and
				542	Static Variables</a>.
				543	</p></div>
				544
				545	<div class="stylebody">
				546
				547	<div class="definition">
				548	<p>Namespaces subdivide the global scope
				549	into distinct, named scopes, and so are useful for preventing
				550	name collisions in the global scope.</p>
				551	</div>
				552
				553	<div class="pros">
				554
				555	<p>Namespaces provide a method for preventing name conflicts
				556	in large programs while allowing most code to use reasonably
				557	short names.</p>
				558
				559	<p>For example, if two different projects have a class
				560	<code>Foo</code> in the global scope, these symbols may
				561	collide at compile time or at runtime. If each project
				562	places their code in a namespace, <code>project1::Foo</code>
				563	and <code>project2::Foo</code> are now distinct symbols that
				564	do not collide, and code within each project's namespace
				565	can continue to refer to <code>Foo</code> without the prefix.</p>
				566
				567	<p>Inline namespaces automatically place their names in
				568	the enclosing scope. Consider the following snippet, for
				569	example:</p>
				570
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	571	<pre>namespace outer {
				572	inline namespace inner {
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	573	void foo();
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	574	} // namespace inner
				575	} // namespace outer
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	576	</pre>
				577
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	578	<p>The expressions <code>outer::inner::foo()</code> and
				579	<code>outer::foo()</code> are interchangeable. Inline
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	580	namespaces are primarily intended for ABI compatibility
				581	across versions.</p>
				582	</div>
				583
				584	<div class="cons">
				585
				586	<p>Namespaces can be confusing, because they complicate
				587	the mechanics of figuring out what definition a name refers
				588	to.</p>
				589
				590	<p>Inline namespaces, in particular, can be confusing
				591	because names aren't actually restricted to the namespace
				592	where they are declared. They are only useful as part of
				593	some larger versioning policy.</p>
				594
				595	<p>In some contexts, it's necessary to repeatedly refer to
				596	symbols by their fully-qualified names. For deeply-nested
				597	namespaces, this can add a lot of clutter.</p>
				598	</div>
				599
				600	<div class="decision">
				601
				602	<p>Namespaces should be used as follows:</p>
				603
				604	<ul>
				605	<li>Follow the rules on <a href="#Namespace_Names">Namespace Names</a>.
				606	</li><li>Terminate namespaces with comments as shown in the given examples.
				607	</li><li>
				608
				609	<p>Namespaces wrap the entire source file after
				610	includes,
				611	<a href="https://gflags.github.io/gflags/">
				612	gflags</a> definitions/declarations
				613	and forward declarations of classes from other namespaces.</p>
				614
				615	<pre>// In the .h file
				616	namespace mynamespace {
				617
				618	// All declarations are within the namespace scope.
				619	// Notice the lack of indentation.
				620	class MyClass {
				621	public:
				622	...
				623	void Foo();
				624	};
				625
				626	} // namespace mynamespace
				627	</pre>
				628
				629	<pre>// In the .cc file
				630	namespace mynamespace {
				631
				632	// Definition of functions is within scope of the namespace.
				633	void MyClass::Foo() {
				634	...
				635	}
				636
				637	} // namespace mynamespace
				638	</pre>
				639
				640	<p>More complex <code>.cc</code> files might have additional details,
				641	like flags or using-declarations.</p>
				642
				643	<pre>#include "a.h"
				644
				645	DEFINE_FLAG(bool, someflag, false, "dummy flag");
				646
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	647	namespace mynamespace {
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	648
				649	using ::foo::bar;
				650
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	651	...code for mynamespace... // Code goes against the left margin.
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	652
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	653	} // namespace mynamespace
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	654	</pre>
				655	</li>
				656
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	657	<li>To place generated protocol
				658	message code in a namespace, use the
				659	<code>package</code> specifier in the
				660	<code>.proto</code> file. See
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	661
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	662	<a href="https://developers.google.com/protocol-buffers/docs/reference/cpp-generated#package">
				663	Protocol Buffer Packages</a>
				664	for details.</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	665
				666	<li>Do not declare anything in namespace
				667	<code>std</code>, including forward declarations of
				668	standard library classes. Declaring entities in
				669	namespace <code>std</code> is undefined behavior, i.e.,
				670	not portable. To declare entities from the standard
				671	library, include the appropriate header file.</li>
				672
				673	<li><p>You may not use a <i>using-directive</i>
				674	to make all names from a namespace available.</p>
				675
				676	<pre class="badcode">// Forbidden -- This pollutes the namespace.
				677	using namespace foo;
				678	</pre>
				679	</li>
				680
				681	<li><p>Do not use <i>Namespace aliases</i> at namespace scope
				682	in header files except in explicitly marked
				683	internal-only namespaces, because anything imported into a namespace
				684	in a header file becomes part of the public
				685	API exported by that file.</p>
				686
				687	<pre>// Shorten access to some commonly used names in .cc files.
				688	namespace baz = ::foo::bar::baz;
				689	</pre>
				690
				691	<pre>// Shorten access to some commonly used names (in a .h file).
				692	namespace librarian {
				693	namespace impl { // Internal, not part of the API.
				694	namespace sidetable = ::pipeline_diagnostics::sidetable;
				695	} // namespace impl
				696
				697	inline void my_inline_function() {
				698	// namespace alias local to a function (or method).
				699	namespace baz = ::foo::bar::baz;
				700	...
				701	}
				702	} // namespace librarian
				703	</pre>
				704
				705	</li><li>Do not use inline namespaces.</li>
				706	</ul>
				707	</div>
				708	</div>
				709
				710	<h3 id="Unnamed_Namespaces_and_Static_Variables">Unnamed Namespaces and Static
				711	Variables</h3>
				712
				713	<div class="summary">
				714	<p>When definitions in a <code>.cc</code> file do not need to be
				715	referenced outside that file, place them in an unnamed
				716	namespace or declare them <code>static</code>. Do not use either
				717	of these constructs in <code>.h</code> files.
				718	</p></div>
				719
				720	<div class="stylebody">
				721
				722	<div class="definition">
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	723	<p>All declarations can be given internal linkage by placing them in unnamed
				724	namespaces. Functions and variables can also be given internal linkage by
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	725	declaring them <code>static</code>. This means that anything you're declaring
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	726	can't be accessed from another file. If a different file declares something with
				727	the same name, then the two entities are completely independent.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	728	</div>
				729
				730	<div class="decision">
				731
				732	<p>Use of internal linkage in <code>.cc</code> files is encouraged
				733	for all code that does not need to be referenced elsewhere.
				734	Do not use internal linkage in <code>.h</code> files.</p>
				735
				736	<p>Format unnamed namespaces like named namespaces. In the
				737	terminating comment, leave the namespace name empty:</p>
				738
				739	<pre>namespace {
				740	...
				741	} // namespace
				742	</pre>
				743	</div>
				744	</div>
				745
				746	<h3 id="Nonmember,_Static_Member,_and_Global_Functions">Nonmember, Static Member, and Global Functions</h3>
				747
				748	<div class="summary">
				749	<p>Prefer placing nonmember functions in a namespace; use completely global
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	750	functions rarely. Do not use a class simply to group static functions. Static
				751	methods of a class should generally be closely related to instances of the
				752	class or the class's static data.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	753	</div>
				754
				755	<div class="stylebody">
				756
				757	<div class="pros">
				758	<p>Nonmember and static member functions can be useful in
				759	some situations. Putting nonmember functions in a
				760	namespace avoids polluting the global namespace.</p>
				761	</div>
				762
				763	<div class="cons">
				764	<p>Nonmember and static member functions may make more sense
				765	as members of a new class, especially if they access
				766	external resources or have significant dependencies.</p>
				767	</div>
				768
				769	<div class="decision">
				770	<p>Sometimes it is useful to define a
				771	function not bound to a class instance. Such a function
				772	can be either a static member or a nonmember function.
				773	Nonmember functions should not depend on external
				774	variables, and should nearly always exist in a namespace.
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	775	Do not create classes only to group static member functions;
				776	this is no different than just giving the function names a
				777	common prefix, and such grouping is usually unnecessary anyway.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	778
				779	<p>If you define a nonmember function and it is only
				780	needed in its <code>.cc</code> file, use
				781	<a href="#Unnamed_Namespaces_and_Static_Variables">internal linkage</a> to limit
				782	its scope.</p>
				783	</div>
				784
				785	</div>
				786
				787	<h3 id="Local_Variables">Local Variables</h3>
				788
				789	<div class="summary">
				790	<p>Place a function's variables in the narrowest scope
				791	possible, and initialize variables in the declaration.</p>
				792	</div>
				793
				794	<div class="stylebody">
				795
				796	<p>C++ allows you to declare variables anywhere in a
				797	function. We encourage you to declare them in as local a
				798	scope as possible, and as close to the first use as
				799	possible. This makes it easier for the reader to find the
				800	declaration and see what type the variable is and what it
				801	was initialized to. In particular, initialization should
				802	be used instead of declaration and assignment, e.g.:</p>
				803
				804	<pre class="badcode">int i;
				805	i = f(); // Bad -- initialization separate from declaration.
				806	</pre>
				807
				808	<pre>int j = g(); // Good -- declaration has initialization.
				809	</pre>
				810
				811	<pre class="badcode">std::vector<int> v;
				812	v.push_back(1); // Prefer initializing using brace initialization.
				813	v.push_back(2);
				814	</pre>
				815
				816	<pre>std::vector<int> v = {1, 2}; // Good -- v starts initialized.
				817	</pre>
				818
				819	<p>Variables needed for <code>if</code>, <code>while</code>
				820	and <code>for</code> statements should normally be declared
				821	within those statements, so that such variables are confined
				822	to those scopes. E.g.:</p>
				823
				824	<pre>while (const char* p = strchr(str, '/')) str = p + 1;
				825	</pre>
				826
				827	<p>There is one caveat: if the variable is an object, its
				828	constructor is invoked every time it enters scope and is
				829	created, and its destructor is invoked every time it goes
				830	out of scope.</p>
				831
				832	<pre class="badcode">// Inefficient implementation:
				833	for (int i = 0; i < 1000000; ++i) {
				834	Foo f; // My ctor and dtor get called 1000000 times each.
				835	f.DoSomething(i);
				836	}
				837	</pre>
				838
				839	<p>It may be more efficient to declare such a variable
				840	used in a loop outside that loop:</p>
				841
				842	<pre>Foo f; // My ctor and dtor get called once each.
				843	for (int i = 0; i < 1000000; ++i) {
				844	f.DoSomething(i);
				845	}
				846	</pre>
				847
				848	</div>
				849
				850	<h3 id="Static_and_Global_Variables">Static and Global Variables</h3>
				851
				852	<div class="summary">
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	853	<p>Objects with
				854	<a href="http://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration">
				855	static storage duration</a> are forbidden unless they are
				856	<a href="http://en.cppreference.com/w/cpp/types/is_destructible">trivially
				857	destructible</a>. Informally this means that the destructor does not do
				858	anything, even taking member and base destructors into account. More formally it
				859	means that the type has no user-defined or virtual destructor and that all bases
				860	and non-static members are trivially destructible.
				861	Static function-local variables may use dynamic initialization.
				862	Use of dynamic initialization for static class member variables or variables at
				863	namespace scope is discouraged, but allowed in limited circumstances; see below
				864	for details.</p>
				865
				866	<p>As a rule of thumb: a global variable satisfies these requirements if its
				867	declaration, considered in isolation, could be <code>constexpr</code>.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	868	</div>
				869
				870	<div class="stylebody">
				871
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	872	<div class="definition">
				873	<p>Every object has a <dfn>storage duration</dfn>, which correlates with its
				874	lifetime. Objects with static storage duration live from the point of their
				875	initialization until the end of the program. Such objects appear as variables at
				876	namespace scope ("global variables"), as static data members of classes, or as
				877	function-local variables that are declared with the <code>static</code>
				878	specifier. Function-local static variables are initialized when control first
				879	passes through their declaration; all other objects with static storage duration
				880	are initialized as part of program start-up. All objects with static storage
				881	duration are destroyed at program exit (which happens before unjoined threads
				882	are terminated).</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	883
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	884	<p>Initialization may be <dfn>dynamic</dfn>, which means that something
				885	non-trivial happens during initialization. (For example, consider a constructor
				886	that allocates memory, or a variable that is initialized with the current
				887	process ID.) The other kind of initialization is <dfn>static</dfn>
				888	initialization. The two aren't quite opposites, though: static
				889	initialization <em>always</em> happens to objects with static storage duration
				890	(initializing the object either to a given constant or to a representation
				891	consisting of all bytes set to zero), whereas dynamic initialization happens
				892	after that, if required.</p>
				893	</div>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	894
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	895	<div class="pros">
				896	<p>Global and static variables are very useful for a large number of
				897	applications: named constants, auxiliary data structures internal to some
				898	translation unit, command-line flags, logging, registration mechanisms,
				899	background infrastructure, etc.</p>
				900	</div>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	901
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	902	<div class="cons">
				903	<p>Global and static variables that use dynamic initialization or have
				904	non-trivial destructors create complexity that can easily lead to hard-to-find
				905	bugs. Dynamic initialization is not ordered across translation units, and
				906	neither is destruction (except that destruction
				907	happens in reverse order of initialization). When one initialization refers to
				908	another variable with static storage duration, it is possible that this causes
				909	an object to be accessed before its lifetime has begun (or after its lifetime
				910	has ended). Moreover, when a program starts threads that are not joined at exit,
				911	those threads may attempt to access objects after their lifetime has ended if
				912	their destructor has already run.</p>
				913	</div>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	914
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	915	<div class="decision">
				916	<h4>Decision on destruction</h4>
				917
				918	<p>When destructors are trivial, their execution is not subject to ordering at
				919	all (they are effectively not "run"); otherwise we are exposed to the risk of
				920	accessing objects after the end of their lifetime. Therefore, we only allow
				921	objects with static storage duration if they are trivially destructible.
				922	Fundamental types (like pointers and <code>int</code>) are trivially
				923	destructible, as are arrays of trivially destructible types. Note that
				924	variables marked with <code>constexpr</code> are trivially destructible.</p>
				925	<pre>const int kNum = 10; // allowed
				926
				927	struct X { int n; };
				928	const X kX[] = {{1}, {2}, {3}}; // allowed
				929
				930	void foo() {
				931	static const char* const kMessages[] = {"hello", "world"}; // allowed
				932	}
				933
				934	// allowed: constexpr guarantees trivial destructor
				935	constexpr std::array<int, 3> kArray = {{1, 2, 3}};</pre>
				936	<pre class="badcode">// bad: non-trivial destructor
				937	const string kFoo = "foo";
				938
				939	// bad for the same reason, even though kBar is a reference (the
				940	// rule also applies to lifetime-extended temporary objects)
				941	const string& kBar = StrCat("a", "b", "c");
				942
				943	void bar() {
				944	// bad: non-trivial destructor
				945	static std::map<int, int> kData = {{1, 0}, {2, 0}, {3, 0}};
				946	}</pre>
				947
				948	<p>Note that references are not objects, and thus they are not subject to the
				949	constraints on destructibility. The constraint on dynamic initialization still
				950	applies, though. In particular, a function-local static reference of the form
				951	<code>static T& t = *new T;</code> is allowed.</p>
				952
				953	<h4>Decision on initialization</h4>
				954
				955	<p>Initialization is a more complex topic. This is because we must not only
				956	consider whether class constructors execute, but we must also consider the
				957	evaluation of the initializer:</p>
				958	<pre class="neutralcode">int n = 5; // fine
				959	int m = f(); // ? (depends on f)
				960	Foo x; // ? (depends on Foo::Foo)
				961	Bar y = g(); // ? (depends on g and on Bar::Bar)</pre>
				962
				963	<p>All but the first statement expose us to indeterminate initialization
				964	ordering.</p>
				965
				966	<p>The concept we are looking for is called <em>constant initialization</em> in
				967	the formal language of the C++ standard. It means that the initializing
				968	expression is a constant expression, and if the object is initialized by a
				969	constructor call, then the constructor must be specified as
				970	<code>constexpr</code>, too:</p>
				971	<pre>struct Foo { constexpr Foo(int) {} };
				972
				973	int n = 5; // fine, 5 is a constant expression
				974	Foo x(2); // fine, 2 is a constant expression and the chosen constructor is constexpr
				975	Foo a[] = { Foo(1), Foo(2), Foo(3) }; // fine</pre>
				976
				977	<p>Constant initialization is always allowed. Constant initialization of
				978	static storage duration variables should be marked with <code>constexpr</code>
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	979	or where possible the
				980
				981	<a href="https://github.com/abseil/abseil-cpp/blob/03c1513538584f4a04d666be5eb469e3979febba/absl/base/attributes.h#L540">
				982	<code>ABSL_CONST_INIT</code></a>
				983	attribute. Any non-local static storage
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	984	duration variable that is not so marked should be presumed to have
				985	dynamic initialization, and reviewed very carefully.</p>
				986
				987	<p>By contrast, the following initializations are problematic:</p>
				988
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	989	<pre class="badcode">// Some declarations used below.
				990	time_t time(time_t*); // not constexpr!
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	991	int f(); // not constexpr!
				992	struct Bar { Bar() {} };
				993
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	994	// Problematic initializations.
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	995	time_t m = time(nullptr); // initializing expression not a constant expression
				996	Foo y(f()); // ditto
				997	Bar b; // chosen constructor Bar::Bar() not constexpr</pre>
				998
				999	<p>Dynamic initialization of nonlocal variables is discouraged, and in general
				1000	it is forbidden. However, we do permit it if no aspect of the program depends
				1001	on the sequencing of this initialization with respect to all other
				1002	initializations. Under those restrictions, the ordering of the initialization
				1003	does not make an observable difference. For example:</p>
				1004	<pre>int p = getpid(); // allowed, as long as no other static variable
				1005	// uses p in its own initialization</pre>
				1006
				1007	<p>Dynamic initialization of static local variables is allowed (and common).</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1008
				1009
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1010	</div>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1011
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1012	<h4>Common patterns</h4>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1013
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1014	<ul>
				1015	<li>Global strings: if you require a global or static string constant,
				1016	consider using a simple character array, or a char pointer to the first
				1017	element of a string literal. String literals have static storage duration
				1018	already and are usually sufficient.</li>
				1019	<li>Maps, sets, and other dynamic containers: if you require a static, fixed
				1020	collection, such as a set to search against or a lookup table, you cannot
				1021	use the dynamic containers from the standard library as a static variable,
				1022	since they have non-trivial destructors. Instead, consider a simple array of
				1023	trivial types, e.g. an array of arrays of ints (for a "map from int to
				1024	int"), or an array of pairs (e.g. pairs of <code>int</code> and <code>const
				1025	char*</code>). For small collections, linear search is entirely sufficient
				1026	(and efficient, due to memory locality). If necessary, keep the collection in
				1027	sorted order and use a binary search algorithm. If you do really prefer a
				1028	dynamic container from the standard library, consider using a function-local
				1029	static pointer, as described below.</li>
				1030	<li>Smart pointers (<code>unique_ptr</code>, <code>shared_ptr</code>): smart
				1031	pointers execute cleanup during destruction and are therefore forbidden.
				1032	Consider whether your use case fits into one of the other patterns described
				1033	in this section. One simple solution is to use a plain pointer to a
				1034	dynamically allocated object and never delete it (see last item).</li>
				1035	<li>Static variables of custom types: if you require static, constant data of
				1036	a type that you need to define yourself, give the type a trivial destructor
				1037	and a <code>constexpr</code> constructor.</li>
				1038	<li>If all else fails, you can create an object dynamically and never delete
				1039	it by binding the pointer to a function-local static pointer variable:
				1040	<code>static const auto* const impl = new T(args...);</code> (If the
				1041	initialization is more complex, it can be moved into a function or lambda
				1042	expression.)</li>
				1043	</ul>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1044
				1045	</div>
				1046
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1047	<h3 id="thread_local">thread_local Variables</h3>
				1048
				1049	<div class="summary">
				1050	<p><code>thread_local</code> variables that aren't declared inside a function
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	1051	must be initialized with a true compile-time constant,
				1052	and this must be enforced by using the
				1053
				1054	<a href="https://github.com/abseil/abseil-cpp/blob/master/absl/base/attributes.h">
				1055	<code>ABSL_CONST_INIT</code></a>
				1056	attribute. Prefer
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1057	<code>thread_local</code> over other ways of defining thread-local data.</p>
				1058	</div>
				1059
				1060	<div class="stylebody">
				1061
				1062	<div class="definition">
				1063	<p>Starting with C++11, variables can be declared with the
				1064	<code>thread_local</code> specifier:</p>
				1065	<pre>thread_local Foo foo = ...;
				1066	</pre>
				1067	<p>Such a variable is actually a collection of objects, so that when different
				1068	threads access it, they are actually accessing different objects.
				1069	<code>thread_local</code> variables are much like
				1070	<a href="#Static_and_Global_Variables">static storage duration variables</a>
				1071	in many respects. For instance, they can be declared at namespace scope,
				1072	inside functions, or as static class members, but not as ordinary class
				1073	members.</p>
				1074
				1075	<p><code>thread_local</code> variable instances are initialized much like
				1076	static variables, except that they must be initialized separately for each
				1077	thread, rather than once at program startup. This means that
				1078	<code>thread_local</code> variables declared within a function are safe, but
				1079	other <code>thread_local</code> variables are subject to the same
				1080	initialization-order issues as static variables (and more besides).</p>
				1081
				1082	<p><code>thread_local</code> variable instances are destroyed when their thread
				1083	terminates, so they do not have the destruction-order issues of static
				1084	variables.</p>
				1085	</div>
				1086
				1087	<div class="pros">
				1088	<ul>
				1089	<li>Thread-local data is inherently safe from races (because only one thread
				1090	can ordinarily access it), which makes <code>thread_local</code> useful for
				1091	concurrent programming.</li>
				1092	<li><code>thread_local</code> is the only standard-supported way of creating
				1093	thread-local data.</li>
				1094	</ul>
				1095	</div>
				1096
				1097	<div class="cons">
				1098	<ul>
				1099	<li>Accessing a <code>thread_local</code> variable may trigger execution of
				1100	an unpredictable and uncontrollable amount of other code.</li>
				1101	<li><code>thread_local</code> variables are effectively global variables,
				1102	and have all the drawbacks of global variables other than lack of
				1103	thread-safety.</li>
				1104	<li>The memory consumed by a <code>thread_local</code> variable scales with
				1105	the number of running threads (in the worst case), which can be quite large
				1106	in a program.</li>
				1107	<li>An ordinary class member cannot be <code>thread_local</code>.</li>
				1108	<li><code>thread_local</code> may not be as efficient as certain compiler
				1109	intrinsics.</li>
				1110	</ul>
				1111	</div>
				1112
				1113	<div class="decision">
				1114	<p><code>thread_local</code> variables inside a function have no safety
				1115	concerns, so they can be used without restriction. Note that you can use
				1116	a function-scope <code>thread_local</code> to simulate a class- or
				1117	namespace-scope <code>thread_local</code> by defining a function or
				1118	static method that exposes it:</p>
				1119
				1120	<pre>Foo& MyThreadLocalFoo() {
				1121	thread_local Foo result = ComplicatedInitialization();
				1122	return result;
				1123	}
				1124	</pre>
				1125
				1126	<p><code>thread_local</code> variables at class or namespace scope must be
				1127	initialized with a true compile-time constant (i.e. they must have no
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	1128	dynamic initialization). To enforce this,
				1129	<code>thread_local</code> variables at class or namespace scope must be
				1130	annotated with
				1131
				1132	<a href="https://github.com/abseil/abseil-cpp/blob/master/absl/base/attributes.h">
				1133	<code>ABSL_CONST_INIT</code></a>
				1134	(or <code>constexpr</code>, but that should be rare):</p>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1135
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	1136	<pre>ABSL_CONST_INIT thread_local Foo foo = ...;
				1137	</pre>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1138
				1139	<p><code>thread_local</code> should be preferred over other mechanisms for
				1140	defining thread-local data.</p>
				1141	</div>
				1142
				1143	</div>
				1144
				1145
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1146	<h2 id="Classes">Classes</h2>
				1147
				1148	<p>Classes are the fundamental unit of code in C++. Naturally,
				1149	we use them extensively. This section lists the main dos and
				1150	don'ts you should follow when writing a class.</p>
				1151
				1152	<h3 id="Doing_Work_in_Constructors">Doing Work in Constructors</h3>
				1153
				1154	<div class="summary">
				1155	<p>Avoid virtual method calls in constructors, and avoid
				1156	initialization that can fail if you can't signal an error.</p>
				1157	</div>
				1158
				1159	<div class="stylebody">
				1160
				1161	<div class="definition">
				1162	<p>It is possible to perform arbitrary initialization in the body
				1163	of the constructor.</p>
				1164	</div>
				1165
				1166	<div class="pros">
				1167	<ul>
				1168	<li>No need to worry about whether the class has been initialized or
				1169	not.</li>
				1170
				1171	<li>Objects that are fully initialized by constructor call can
				1172	be <code>const</code> and may also be easier to use with standard containers
				1173	or algorithms.</li>
				1174	</ul>
				1175
				1176	</div>
				1177
				1178	<div class="cons">
				1179	<ul>
				1180	<li>If the work calls virtual functions, these calls
				1181	will not get dispatched to the subclass
				1182	implementations. Future modification to your class can
				1183	quietly introduce this problem even if your class is
				1184	not currently subclassed, causing much confusion.</li>
				1185
				1186	<li>There is no easy way for constructors to signal errors, short of
				1187	crashing the program (not always appropriate) or using exceptions
				1188	(which are <a href="#Exceptions">forbidden</a>).</li>
				1189
				1190	<li>If the work fails, we now have an object whose initialization
				1191	code failed, so it may be an unusual state requiring a <code>bool
				1192	IsValid()</code> state checking mechanism (or similar) which is easy
				1193	to forget to call.</li>
				1194
				1195	<li>You cannot take the address of a constructor, so whatever work
				1196	is done in the constructor cannot easily be handed off to, for
				1197	example, another thread.</li>
				1198	</ul>
				1199	</div>
				1200
				1201
				1202	<div class="decision">
				1203	<p>Constructors should never call virtual functions. If appropriate
				1204	for your code
				1205	,
				1206	terminating the program may be an appropriate error handling
				1207	response. Otherwise, consider a factory function
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	1208	or <code>Init()</code> method as described in
				1209
				1210
				1211	<a href="https://abseil.io/tips/42">TotW #42</a>
				1212	.
				1213	Avoid <code>Init()</code> methods on objects with
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1214	no other states that affect which public methods may be called
				1215	(semi-constructed objects of this form are particularly hard to work
				1216	with correctly).</p>
				1217	</div>
				1218
				1219	</div>
				1220
				1221	<a id="Explicit_Constructors"></a>
				1222	<h3 id="Implicit_Conversions">Implicit Conversions</h3>
				1223
				1224	<div class="summary">
				1225	<p>Do not define implicit conversions. Use the <code>explicit</code>
				1226	keyword for conversion operators and single-argument
				1227	constructors.</p>
				1228	</div>
				1229
				1230	<div class="stylebody">
				1231
				1232	<div class="definition">
				1233	<p>Implicit conversions allow an
				1234	object of one type (called the <dfn>source type</dfn>) to
				1235	be used where a different type (called the <dfn>destination
				1236	type</dfn>) is expected, such as when passing an
				1237	<code>int</code> argument to a function that takes a
				1238	<code>double</code> parameter.</p>
				1239
				1240	<p>In addition to the implicit conversions defined by the language,
				1241	users can define their own, by adding appropriate members to the
				1242	class definition of the source or destination type. An implicit
				1243	conversion in the source type is defined by a type conversion operator
				1244	named after the destination type (e.g. <code>operator
				1245	bool()</code>). An implicit conversion in the destination
				1246	type is defined by a constructor that can take the source type as
				1247	its only argument (or only argument with no default value).</p>
				1248
				1249	<p>The <code>explicit</code> keyword can be applied to a constructor
				1250	or (since C++11) a conversion operator, to ensure that it can only be
				1251	used when the destination type is explicit at the point of use,
				1252	e.g. with a cast. This applies not only to implicit conversions, but to
				1253	C++11's list initialization syntax:</p>
				1254	<pre>class Foo {
				1255	explicit Foo(int x, double y);
				1256	...
				1257	};
				1258
				1259	void Func(Foo f);
				1260	</pre>
				1261	<pre class="badcode">Func({42, 3.14}); // Error
				1262	</pre>
				1263	This kind of code isn't technically an implicit conversion, but the
				1264	language treats it as one as far as <code>explicit</code> is concerned.
				1265	</div>
				1266
				1267	<div class="pros">
				1268	<ul>
				1269	<li>Implicit conversions can make a type more usable and
				1270	expressive by eliminating the need to explicitly name a type
				1271	when it's obvious.</li>
				1272	<li>Implicit conversions can be a simpler alternative to
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	1273	overloading, such as when a single
				1274	function with a <code>string_view</code> parameter takes the
				1275	place of separate overloads for <code>string</code> and
				1276	<code>const char*</code>.</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1277	<li>List initialization syntax is a concise and expressive
				1278	way of initializing objects.</li>
				1279	</ul>
				1280	</div>
				1281
				1282	<div class="cons">
				1283	<ul>
				1284	<li>Implicit conversions can hide type-mismatch bugs, where the
				1285	destination type does not match the user's expectation, or
				1286	the user is unaware that any conversion will take place.</li>
				1287
				1288	<li>Implicit conversions can make code harder to read, particularly
				1289	in the presence of overloading, by making it less obvious what
				1290	code is actually getting called.</li>
				1291
				1292	<li>Constructors that take a single argument may accidentally
				1293	be usable as implicit type conversions, even if they are not
				1294	intended to do so.</li>
				1295
				1296	<li>When a single-argument constructor is not marked
				1297	<code>explicit</code>, there's no reliable way to tell whether
				1298	it's intended to define an implicit conversion, or the author
				1299	simply forgot to mark it.</li>
				1300
				1301	<li>It's not always clear which type should provide the conversion,
				1302	and if they both do, the code becomes ambiguous.</li>
				1303
				1304	<li>List initialization can suffer from the same problems if
				1305	the destination type is implicit, particularly if the
				1306	list has only a single element.</li>
				1307	</ul>
				1308	</div>
				1309
				1310	<div class="decision">
				1311	<p>Type conversion operators, and constructors that are
				1312	callable with a single argument, must be marked
				1313	<code>explicit</code> in the class definition. As an
				1314	exception, copy and move constructors should not be
				1315	<code>explicit</code>, since they do not perform type
				1316	conversion. Implicit conversions can sometimes be necessary and
				1317	appropriate for types that are designed to transparently wrap other
				1318	types. In that case, contact
				1319	your project leads to request
				1320	a waiver of this rule.</p>
				1321
				1322	<p>Constructors that cannot be called with a single argument
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1323	may omit <code>explicit</code>. Constructors that
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1324	take a single <code>std::initializer_list</code> parameter should
				1325	also omit <code>explicit</code>, in order to support copy-initialization
				1326	(e.g. <code>MyType m = {1, 2};</code>).</p>
				1327	</div>
				1328
				1329	</div>
				1330
				1331	<h3 id="Copyable_Movable_Types">Copyable and Movable Types</h3>
				1332	<a id="Copy_Constructors"></a>
				1333	<div class="summary">
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1334	<p>A class's public API should make explicit whether the class is copyable,
				1335	move-only, or neither copyable nor movable. Support copying and/or
				1336	moving if these operations are clear and meaningful for your type.</p>
				1337	</div>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1338
				1339	<div class="stylebody">
				1340
				1341	<div class="definition">
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1342	<p>A movable type is one that can be initialized and assigned
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1343	from temporaries.</p>
				1344
				1345	<p>A copyable type is one that can be initialized or assigned from
				1346	any other object of the same type (so is also movable by definition), with the
				1347	stipulation that the value of the source does not change.
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1348	<code>std::unique_ptr<int></code> is an example of a movable but not
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1349	copyable type (since the value of the source
				1350	<code>std::unique_ptr<int></code> must be modified during assignment to
				1351	the destination). <code>int</code> and <code>string</code> are examples of
				1352	movable types that are also copyable. (For <code>int</code>, the move and copy
				1353	operations are the same; for <code>string</code>, there exists a move operation
				1354	that is less expensive than a copy.)</p>
				1355
				1356	<p>For user-defined types, the copy behavior is defined by the copy
				1357	constructor and the copy-assignment operator. Move behavior is defined by the
				1358	move constructor and the move-assignment operator, if they exist, or by the
				1359	copy constructor and the copy-assignment operator otherwise.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1360
				1361	<p>The copy/move constructors can be implicitly invoked by the compiler
				1362	in some situations, e.g. when passing objects by value.</p>
				1363	</div>
				1364
				1365	<div class="pros">
				1366	<p>Objects of copyable and movable types can be passed and returned by value,
				1367	which makes APIs simpler, safer, and more general. Unlike when passing objects
				1368	by pointer or reference, there's no risk of confusion over ownership,
				1369	lifetime, mutability, and similar issues, and no need to specify them in the
				1370	contract. It also prevents non-local interactions between the client and the
				1371	implementation, which makes them easier to understand, maintain, and optimize by
				1372	the compiler. Further, such objects can be used with generic APIs that
				1373	require pass-by-value, such as most containers, and they allow for additional
				1374	flexibility in e.g., type composition.</p>
				1375
				1376	<p>Copy/move constructors and assignment operators are usually
				1377	easier to define correctly than alternatives
				1378	like <code>Clone()</code>, <code>CopyFrom()</code> or <code>Swap()</code>,
				1379	because they can be generated by the compiler, either implicitly or
				1380	with <code>= default</code>. They are concise, and ensure
				1381	that all data members are copied. Copy and move
				1382	constructors are also generally more efficient, because they don't
				1383	require heap allocation or separate initialization and assignment
				1384	steps, and they're eligible for optimizations such as
				1385
				1386	<a href="http://en.cppreference.com/w/cpp/language/copy_elision">
				1387	copy elision</a>.</p>
				1388
				1389	<p>Move operations allow the implicit and efficient transfer of
				1390	resources out of rvalue objects. This allows a plainer coding style
				1391	in some cases.</p>
				1392	</div>
				1393
				1394	<div class="cons">
				1395	<p>Some types do not need to be copyable, and providing copy
				1396	operations for such types can be confusing, nonsensical, or outright
				1397	incorrect. Types representing singleton objects (<code>Registerer</code>),
				1398	objects tied to a specific scope (<code>Cleanup</code>), or closely coupled to
				1399	object identity (<code>Mutex</code>) cannot be copied meaningfully.
				1400	Copy operations for base class types that are to be used
				1401	polymorphically are hazardous, because use of them can lead to
				1402	<a href="https://en.wikipedia.org/wiki/Object_slicing">object slicing</a>.
				1403	Defaulted or carelessly-implemented copy operations can be incorrect, and the
				1404	resulting bugs can be confusing and difficult to diagnose.</p>
				1405
				1406	<p>Copy constructors are invoked implicitly, which makes the
				1407	invocation easy to miss. This may cause confusion for programmers used to
				1408	languages where pass-by-reference is conventional or mandatory. It may also
				1409	encourage excessive copying, which can cause performance problems.</p>
				1410	</div>
				1411
				1412	<div class="decision">
				1413
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1414	<p>Every class's public interface should make explicit which copy and move
				1415	operations the class supports. This should usually take the form of explicitly
				1416	declaring and/or deleting the appropriate operations in the <code>public</code>
				1417	section of the declaration.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1418
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1419	<p>Specifically, a copyable class should explicitly declare the copy
				1420	operations, a move-only class should explicitly declare the move operations,
				1421	and a non-copyable/movable class should explicitly delete the copy operations.
				1422	Explicitly declaring or deleting all four copy/move operations is permitted,
				1423	but not required. If you provide a copy or move assignment operator, you
				1424	must also provide the corresponding constructor.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1425
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1426	<pre>class Copyable {
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1427	public:
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1428	Copyable(const Copyable& rhs) = default;
				1429	Copyable& operator=(const Copyable& rhs) = default;
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1430
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1431	// The implicit move operations are suppressed by the declarations above.
				1432	};
				1433
				1434	class MoveOnly {
				1435	public:
				1436	MoveOnly(MoveOnly&& rhs);
				1437	MoveOnly& operator=(MoveOnly&& rhs);
				1438
				1439	// The copy operations are implicitly deleted, but you can
				1440	// spell that out explicitly if you want:
				1441	MoveOnly(const MoveOnly&) = delete;
				1442	MoveOnly& operator=(const MoveOnly&) = delete;
				1443	};
				1444
				1445	class NotCopyableOrMovable {
				1446	public:
				1447	// Not copyable or movable
				1448	NotCopyableOrMovable(const NotCopyableOrMovable&) = delete;
				1449	NotCopyableOrMovable& operator=(const NotCopyableOrMovable&)
				1450	= delete;
				1451
				1452	// The move operations are implicitly disabled, but you can
				1453	// spell that out explicitly if you want:
				1454	NotCopyableOrMovable(NotCopyableOrMovable&&) = delete;
				1455	NotCopyableOrMovable& operator=(NotCopyableOrMovable&&)
				1456	= delete;
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1457	};
				1458	</pre>
				1459
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1460	<p>These declarations/deletions can be omitted only if they are obvious: for
				1461	example, if a base class isn't copyable or movable, derived classes naturally
				1462	won't be either. Similarly, a <a href="#Structs_vs._Classes">struct</a>'s
				1463	copyability/movability is normally determined by the copyability/movability
				1464	of its data members (this does not apply to classes because in Google code
				1465	their data members are not public). Note that if you explicitly declare or
				1466	delete any of the copy/move operations, the others are not obvious, and so
				1467	this paragraph does not apply (in particular, the rules in this section
				1468	that apply to "classes" also apply to structs that declare or delete any
				1469	copy/move operations).</p>
				1470
				1471	<p>A type should not be copyable/movable if the meaning of
				1472	copying/moving is unclear to a casual user, or if it incurs unexpected
				1473	costs. Move operations for copyable types are strictly a performance
				1474	optimization and are a potential source of bugs and complexity, so
				1475	avoid defining them unless they are significantly more efficient than
				1476	the corresponding copy operations. If your type provides copy operations, it is
				1477	recommended that you design your class so that the default implementation of
				1478	those operations is correct. Remember to review the correctness of any
				1479	defaulted operations as you would any other code.</p>
				1480
				1481	<p>Due to the risk of slicing, prefer to avoid providing a public assignment
				1482	operator or copy/move constructor for a class that's
				1483	intended to be derived from (and prefer to avoid deriving from a class
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1484	with such members). If your base class needs to be
				1485	copyable, provide a public virtual <code>Clone()</code>
				1486	method, and a protected copy constructor that derived classes
				1487	can use to implement it.</p>
				1488
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1489
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1490
				1491	</div>
				1492	</div>
				1493
				1494	<h3 id="Structs_vs._Classes">Structs vs. Classes</h3>
				1495
				1496	<div class="summary">
				1497	<p>Use a <code>struct</code> only for passive objects that
				1498	carry data; everything else is a <code>class</code>.</p>
				1499	</div>
				1500
				1501	<div class="stylebody">
				1502
				1503	<p>The <code>struct</code> and <code>class</code>
				1504	keywords behave almost identically in C++. We add our own
				1505	semantic meanings to each keyword, so you should use the
				1506	appropriate keyword for the data-type you're
				1507	defining.</p>
				1508
				1509	<p><code>structs</code> should be used for passive
				1510	objects that carry data, and may have associated
				1511	constants, but lack any functionality other than
				1512	access/setting the data members. The accessing/setting of
				1513	fields is done by directly accessing the fields rather
				1514	than through method invocations. Methods should not
				1515	provide behavior but should only be used to set up the
				1516	data members, e.g., constructor, destructor,
				1517	<code>Initialize()</code>, <code>Reset()</code>,
				1518	<code>Validate()</code>.</p>
				1519
				1520	<p>If more functionality is required, a
				1521	<code>class</code> is more appropriate. If in doubt, make
				1522	it a <code>class</code>.</p>
				1523
				1524	<p>For consistency with STL, you can use
				1525	<code>struct</code> instead of <code>class</code> for
				1526	functors and traits.</p>
				1527
				1528	<p>Note that member variables in structs and classes have
				1529	<a href="#Variable_Names">different naming rules</a>.</p>
				1530
				1531	</div>
				1532
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	1533	<a id="Multiple_Inheritance"></a>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1534	<h3 id="Inheritance">Inheritance</h3>
				1535
				1536	<div class="summary">
				1537	<p>Composition is often more appropriate than inheritance.
				1538	When using inheritance, make it <code>public</code>.</p>
				1539	</div>
				1540
				1541	<div class="stylebody">
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1542	<div class="definition">
				1543	<p> When a sub-class
				1544	inherits from a base class, it includes the definitions
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	1545	of all the data and operations that the base class
				1546	defines. "Interface inheritance" is inheritance from a
				1547	pure abstract base class (one with no state or defined
				1548	methods); all other inheritance is "implementation
				1549	inheritance".</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1550	</div>
				1551
				1552	<div class="pros">
				1553	<p>Implementation inheritance reduces code size by re-using
				1554	the base class code as it specializes an existing type.
				1555	Because inheritance is a compile-time declaration, you
				1556	and the compiler can understand the operation and detect
				1557	errors. Interface inheritance can be used to
				1558	programmatically enforce that a class expose a particular
				1559	API. Again, the compiler can detect errors, in this case,
				1560	when a class does not define a necessary method of the
				1561	API.</p>
				1562	</div>
				1563
				1564	<div class="cons">
				1565	<p>For implementation inheritance, because the code
				1566	implementing a sub-class is spread between the base and
				1567	the sub-class, it can be more difficult to understand an
				1568	implementation. The sub-class cannot override functions
				1569	that are not virtual, so the sub-class cannot change
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1570	implementation.</p>
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	1571
				1572	<p>Multiple inheritance is especially problematic, because
				1573	it often imposes a higher performance overhead (in fact,
				1574	the performance drop from single inheritance to multiple
				1575	inheritance can often be greater than the performance
				1576	drop from ordinary to virtual dispatch), and because
				1577	it risks leading to "diamond" inheritance patterns,
				1578	which are prone to ambiguity, confusion, and outright bugs.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1579	</div>
				1580
				1581	<div class="decision">
				1582
				1583	<p>All inheritance should be <code>public</code>. If you
				1584	want to do private inheritance, you should be including
				1585	an instance of the base class as a member instead.</p>
				1586
				1587	<p>Do not overuse implementation inheritance. Composition
				1588	is often more appropriate. Try to restrict use of
				1589	inheritance to the "is-a" case: <code>Bar</code>
				1590	subclasses <code>Foo</code> if it can reasonably be said
				1591	that <code>Bar</code> "is a kind of"
				1592	<code>Foo</code>.</p>
				1593
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1594	<p>Limit the use of <code>protected</code> to those
				1595	member functions that might need to be accessed from
				1596	subclasses. Note that <a href="#Access_Control">data
				1597	members should be private</a>.</p>
				1598
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1599	<p>Explicitly annotate overrides of virtual functions or virtual
				1600	destructors with exactly one of an <code>override</code> or (less
				1601	frequently) <code>final</code> specifier. Do not
				1602	use <code>virtual</code> when declaring an override.
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1603	Rationale: A function or destructor marked
				1604	<code>override</code> or <code>final</code> that is
				1605	not an override of a base class virtual function will
				1606	not compile, and this helps catch common errors. The
				1607	specifiers serve as documentation; if no specifier is
				1608	present, the reader has to check all ancestors of the
				1609	class in question to determine if the function or
				1610	destructor is virtual or not.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1611
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	1612	<p>Multiple inheritance is permitted, but multiple <em>implementation</em>
				1613	inheritance is strongly discouraged.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1614	</div>
				1615
				1616	</div>
				1617
				1618	<h3 id="Operator_Overloading">Operator Overloading</h3>
				1619
				1620	<div class="summary">
				1621	<p>Overload operators judiciously. Do not create user-defined literals.</p>
				1622	</div>
				1623
				1624	<div class="stylebody">
				1625
				1626	<div class="definition">
				1627	<p>C++ permits user code to
				1628	<a href="http://en.cppreference.com/w/cpp/language/operators">declare
				1629	overloaded versions of the built-in operators</a> using the
				1630	<code>operator</code> keyword, so long as one of the parameters
				1631	is a user-defined type. The <code>operator</code> keyword also
				1632	permits user code to define new kinds of literals using
				1633	<code>operator""</code>, and to define type-conversion functions
				1634	such as <code>operator bool()</code>.</p>
				1635	</div>
				1636
				1637	<div class="pros">
				1638	<p>Operator overloading can make code more concise and
				1639	intuitive by enabling user-defined types to behave the same
				1640	as built-in types. Overloaded operators are the idiomatic names
				1641	for certain operations (e.g. <code>==</code>, <code><</code>,
				1642	<code>=</code>, and <code><<</code>), and adhering to
				1643	those conventions can make user-defined types more readable
				1644	and enable them to interoperate with libraries that expect
				1645	those names.</p>
				1646
				1647	<p>User-defined literals are a very concise notation for
				1648	creating objects of user-defined types.</p>
				1649	</div>
				1650
				1651	<div class="cons">
				1652	<ul>
				1653	<li>Providing a correct, consistent, and unsurprising
				1654	set of operator overloads requires some care, and failure
				1655	to do so can lead to confusion and bugs.</li>
				1656
				1657	<li>Overuse of operators can lead to obfuscated code,
				1658	particularly if the overloaded operator's semantics
				1659	don't follow convention.</li>
				1660
				1661	<li>The hazards of function overloading apply just as
				1662	much to operator overloading, if not more so.</li>
				1663
				1664	<li>Operator overloads can fool our intuition into
				1665	thinking that expensive operations are cheap, built-in
				1666	operations.</li>
				1667
				1668	<li>Finding the call sites for overloaded operators may
				1669	require a search tool that's aware of C++ syntax, rather
				1670	than e.g. grep.</li>
				1671
				1672	<li>If you get the argument type of an overloaded operator
				1673	wrong, you may get a different overload rather than a
				1674	compiler error. For example, <code>foo < bar</code>
				1675	may do one thing, while <code>&foo < &bar</code>
				1676	does something totally different.</li>
				1677
				1678	<li>Certain operator overloads are inherently hazardous.
				1679	Overloading unary <code>&</code> can cause the same
				1680	code to have different meanings depending on whether
				1681	the overload declaration is visible. Overloads of
				1682	<code>&&</code>, <code>\|\|</code>, and <code>,</code>
				1683	(comma) cannot match the evaluation-order semantics of the
				1684	built-in operators.</li>
				1685
				1686	<li>Operators are often defined outside the class,
				1687	so there's a risk of different files introducing
				1688	different definitions of the same operator. If both
				1689	definitions are linked into the same binary, this results
				1690	in undefined behavior, which can manifest as subtle
				1691	run-time bugs.</li>
				1692
				1693	<li>User-defined literals allow the creation of new
				1694	syntactic forms that are unfamiliar even to experienced C++
				1695	programmers.</li>
				1696	</ul>
				1697	</div>
				1698
				1699	<div class="decision">
				1700	<p>Define overloaded operators only if their meaning is
				1701	obvious, unsurprising, and consistent with the corresponding
				1702	built-in operators. For example, use <code>\|</code> as a
				1703	bitwise- or logical-or, not as a shell-style pipe.</p>
				1704
				1705	<p>Define operators only on your own types. More precisely,
				1706	define them in the same headers, .cc files, and namespaces
				1707	as the types they operate on. That way, the operators are available
				1708	wherever the type is, minimizing the risk of multiple
				1709	definitions. If possible, avoid defining operators as templates,
				1710	because they must satisfy this rule for any possible template
				1711	arguments. If you define an operator, also define
				1712	any related operators that make sense, and make sure they
				1713	are defined consistently. For example, if you overload
				1714	<code><</code>, overload all the comparison operators,
				1715	and make sure <code><</code> and <code>></code> never
				1716	return true for the same arguments.</p>
				1717
				1718	<p>Prefer to define non-modifying binary operators as
				1719	non-member functions. If a binary operator is defined as a
				1720	class member, implicit conversions will apply to the
				1721	right-hand argument, but not the left-hand one. It will
				1722	confuse your users if <code>a < b</code> compiles but
				1723	<code>b < a</code> doesn't.</p>
				1724
				1725	<p>Don't go out of your way to avoid defining operator
				1726	overloads. For example, prefer to define <code>==</code>,
				1727	<code>=</code>, and <code><<</code>, rather than
				1728	<code>Equals()</code>, <code>CopyFrom()</code>, and
				1729	<code>PrintTo()</code>. Conversely, don't define
				1730	operator overloads just because other libraries expect
				1731	them. For example, if your type doesn't have a natural
				1732	ordering, but you want to store it in a <code>std::set</code>,
				1733	use a custom comparator rather than overloading
				1734	<code><</code>.</p>
				1735
				1736	<p>Do not overload <code>&&</code>, <code>\|\|</code>,
				1737	<code>,</code> (comma), or unary <code>&</code>. Do not overload
				1738	<code>operator""</code>, i.e. do not introduce user-defined
				1739	literals.</p>
				1740
				1741	<p>Type conversion operators are covered in the section on
				1742	<a href="#Implicit_Conversions">implicit conversions</a>.
				1743	The <code>=</code> operator is covered in the section on
				1744	<a href="#Copy_Constructors">copy constructors</a>. Overloading
				1745	<code><<</code> for use with streams is covered in the
				1746	section on <a href="#Streams">streams</a>. See also the rules on
				1747	<a href="#Function_Overloading">function overloading</a>, which
				1748	apply to operator overloading as well.</p>
				1749	</div>
				1750
				1751	</div>
				1752
				1753	<h3 id="Access_Control">Access Control</h3>
				1754
				1755	<div class="summary">
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	1756	<p>Make classes' data members <code>private</code>, unless they are
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1757	<code>static const</code> (and follow the <a href="#Constant_Names">
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1758	naming convention for constants</a>).</p>
				1759	</div>
				1760
				1761	<div class="stylebody">
				1762
				1763	<p>For technical
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	1764	reasons, we allow data members of a test fixture class in a .cc file to
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1765	be <code>protected</code> when using
				1766
				1767
				1768	<a href="https://github.com/google/googletest">Google
				1769	Test</a>).</p>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1770
				1771	</div>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1772
				1773	<h3 id="Declaration_Order">Declaration Order</h3>
				1774
				1775	<div class="summary">
				1776	<p>Group similar declarations together, placing public parts
				1777	earlier.</p>
				1778	</div>
				1779
				1780	<div class="stylebody">
				1781
				1782	<p>A class definition should usually start with a
				1783	<code>public:</code> section, followed by
				1784	<code>protected:</code>, then <code>private:</code>. Omit
				1785	sections that would be empty.</p>
				1786
				1787	<p>Within each section, generally prefer grouping similar
				1788	kinds of declarations together, and generally prefer the
				1789	following order: types (including <code>typedef</code>,
				1790	<code>using</code>, and nested structs and classes),
				1791	constants, factory functions, constructors, assignment
				1792	operators, destructor, all other methods, data members.</p>
				1793
				1794	<p>Do not put large method definitions inline in the
				1795	class definition. Usually, only trivial or
				1796	performance-critical, and very short, methods may be
				1797	defined inline. See <a href="#Inline_Functions">Inline
				1798	Functions</a> for more details.</p>
				1799
				1800	</div>
				1801
				1802	<h2 id="Functions">Functions</h2>
				1803
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1804	<a id="Function_Parameter_Ordering"></a>
				1805	<h3 id="Output_Parameters">Output Parameters</h3>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1806
				1807	<div class="summary">
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1808	<p>Prefer using return values rather than output parameters.
				1809	If output-only parameters are used they should appear after
				1810	input parameters.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1811	</div>
				1812
				1813	<div class="stylebody">
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1814	<p>The output of a C++ function is naturally provided via
				1815	a return value and sometimes via output parameters.</p>
				1816
				1817	<p>Prefer using return values instead of output parameters
				1818	since they improve readability and oftentimes provide the same
				1819	or better performance.</p>
				1820
				1821	<p>Parameters are either input to the function, output from the
				1822	function, or both. Input parameters are usually values or
				1823	<code>const</code> references, while output and input/output
				1824	parameters will be pointers to non-<code>const</code>.</p>
				1825
				1826	<p>When ordering function parameters, put all input-only
				1827	parameters before any output parameters. In particular,
				1828	do not add new parameters to the end of the function just
				1829	because they are new; place new input-only parameters before
				1830	the output parameters.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1831
				1832	<p>This is not a hard-and-fast rule. Parameters that are
				1833	both input and output (often classes/structs) muddy the
				1834	waters, and, as always, consistency with related
				1835	functions may require you to bend the rule.</p>
				1836
				1837	</div>
				1838
				1839	<h3 id="Write_Short_Functions">Write Short Functions</h3>
				1840
				1841	<div class="summary">
				1842	<p>Prefer small and focused functions.</p>
				1843	</div>
				1844
				1845	<div class="stylebody">
				1846	<p>We recognize that long functions are sometimes
				1847	appropriate, so no hard limit is placed on functions
				1848	length. If a function exceeds about 40 lines, think about
				1849	whether it can be broken up without harming the structure
				1850	of the program.</p>
				1851
				1852	<p>Even if your long function works perfectly now,
				1853	someone modifying it in a few months may add new
				1854	behavior. This could result in bugs that are hard to
				1855	find. Keeping your functions short and simple makes it
				1856	easier for other people to read and modify your code.</p>
				1857
				1858	<p>You could find long and complicated functions when
				1859	working with
				1860	some code. Do not be
				1861	intimidated by modifying existing code: if working with
				1862	such a function proves to be difficult, you find that
				1863	errors are hard to debug, or you want to use a piece of
				1864	it in several different contexts, consider breaking up
				1865	the function into smaller and more manageable pieces.</p>
				1866
				1867	</div>
				1868
				1869	<h3 id="Reference_Arguments">Reference Arguments</h3>
				1870
				1871	<div class="summary">
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	1872	<p>All parameters passed by lvalue reference must be labeled
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1873	<code>const</code>.</p>
				1874	</div>
				1875
				1876	<div class="stylebody">
				1877
				1878	<div class="definition">
				1879	<p>In C, if a
				1880	function needs to modify a variable, the parameter must
				1881	use a pointer, eg <code>int foo(int *pval)</code>. In
				1882	C++, the function can alternatively declare a reference
				1883	parameter: <code>int foo(int &val)</code>.</p>
				1884	</div>
				1885
				1886	<div class="pros">
				1887	<p>Defining a parameter as reference avoids ugly code like
				1888	<code>(*pval)++</code>. Necessary for some applications
				1889	like copy constructors. Makes it clear, unlike with
				1890	pointers, that a null pointer is not a possible
				1891	value.</p>
				1892	</div>
				1893
				1894	<div class="cons">
				1895	<p>References can be confusing, as they have value syntax
				1896	but pointer semantics.</p>
				1897	</div>
				1898
				1899	<div class="decision">
				1900	<p>Within function parameter lists all references must be
				1901	<code>const</code>:</p>
				1902
				1903	<pre>void Foo(const string &in, string *out);
				1904	</pre>
				1905
				1906	<p>In fact it is a very strong convention in Google code
				1907	that input arguments are values or <code>const</code>
				1908	references while output arguments are pointers. Input
				1909	parameters may be <code>const</code> pointers, but we
				1910	never allow non-<code>const</code> reference parameters
				1911	except when required by convention, e.g.,
				1912	<code>swap()</code>.</p>
				1913
				1914	<p>However, there are some instances where using
				1915	<code>const T*</code> is preferable to <code>const
				1916	T&</code> for input parameters. For example:</p>
				1917
				1918	<ul>
				1919	<li>You want to pass in a null pointer.</li>
				1920
				1921	<li>The function saves a pointer or reference to the
				1922	input.</li>
				1923	</ul>
				1924
				1925	<p> Remember that most of the time input
				1926	parameters are going to be specified as <code>const
				1927	T&</code>. Using <code>const T*</code> instead
				1928	communicates to the reader that the input is somehow
				1929	treated differently. So if you choose <code>const
				1930	T*</code> rather than <code>const T&</code>, do so
				1931	for a concrete reason; otherwise it will likely confuse
				1932	readers by making them look for an explanation that
				1933	doesn't exist.</p>
				1934	</div>
				1935
				1936	</div>
				1937
				1938	<h3 id="Function_Overloading">Function Overloading</h3>
				1939
				1940	<div class="summary">
				1941	<p>Use overloaded functions (including constructors) only if a
				1942	reader looking at a call site can get a good idea of what
				1943	is happening without having to first figure out exactly
				1944	which overload is being called.</p>
				1945	</div>
				1946
				1947	<div class="stylebody">
				1948
				1949	<div class="definition">
				1950	<p>You may write a function that takes a <code>const
				1951	string&</code> and overload it with another that
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	1952	takes <code>const char*</code>. However, in this case consider
				1953	std::string_view
				1954	instead.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1955
				1956	<pre>class MyClass {
				1957	public:
				1958	void Analyze(const string &text);
				1959	void Analyze(const char *text, size_t textlen);
				1960	};
				1961	</pre>
				1962	</div>
				1963
				1964	<div class="pros">
				1965	<p>Overloading can make code more intuitive by allowing an
				1966	identically-named function to take different arguments.
				1967	It may be necessary for templatized code, and it can be
				1968	convenient for Visitors.</p>
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	1969	<p>Overloading based on const or ref qualification may make utility
				1970	code more usable, more efficient, or both.
				1971
				1972	(See <a href="http://abseil.io/tips/148">TotW 148</a> for more.)
				1973	</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1974	</div>
				1975
				1976	<div class="cons">
				1977	<p>If a function is overloaded by the argument types alone,
				1978	a reader may have to understand C++'s complex matching
				1979	rules in order to tell what's going on. Also many people
				1980	are confused by the semantics of inheritance if a derived
				1981	class overrides only some of the variants of a
				1982	function.</p>
				1983	</div>
				1984
				1985	<div class="decision">
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	1986	<p>You may overload a function when there are no semantic differences
				1987	between variants. These overloads may vary in types, qualifiers, or
				1988	argument count. However, a reader of such a call must not need to know
				1989	which member of the overload set is chosen, only that <b>something</b>
				1990	from the set is being called. If you can document all entries in the
				1991	overload set with a single comment in the header, that is a good sign
				1992	that it is a well-designed overload set.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	1993	</div>
				1994
				1995	</div>
				1996
				1997	<h3 id="Default_Arguments">Default Arguments</h3>
				1998
				1999	<div class="summary">
				2000	<p>Default arguments are allowed on non-virtual functions
				2001	when the default is guaranteed to always have the same
				2002	value. Follow the same restrictions as for <a href="#Function_Overloading">function overloading</a>, and
				2003	prefer overloaded functions if the readability gained with
				2004	default arguments doesn't outweigh the downsides below.</p>
				2005	</div>
				2006
				2007	<div class="stylebody">
				2008
				2009	<div class="pros">
				2010	<p>Often you have a function that uses default values, but
				2011	occasionally you want to override the defaults. Default
				2012	parameters allow an easy way to do this without having to
				2013	define many functions for the rare exceptions. Compared
				2014	to overloading the function, default arguments have a
				2015	cleaner syntax, with less boilerplate and a clearer
				2016	distinction between 'required' and 'optional'
				2017	arguments.</p>
				2018	</div>
				2019
				2020	<div class="cons">
				2021	<p>Defaulted arguments are another way to achieve the
				2022	semantics of overloaded functions, so all the <a href="#Function_Overloading">reasons not to overload
				2023	functions</a> apply.</p>
				2024
				2025	<p>The defaults for arguments in a virtual function call are
				2026	determined by the static type of the target object, and
				2027	there's no guarantee that all overrides of a given function
				2028	declare the same defaults.</p>
				2029
				2030	<p>Default parameters are re-evaluated at each call site,
				2031	which can bloat the generated code. Readers may also expect
				2032	the default's value to be fixed at the declaration instead
				2033	of varying at each call.</p>
				2034
				2035	<p>Function pointers are confusing in the presence of
				2036	default arguments, since the function signature often
				2037	doesn't match the call signature. Adding
				2038	function overloads avoids these problems.</p>
				2039	</div>
				2040
				2041	<div class="decision">
				2042	<p>Default arguments are banned on virtual functions, where
				2043	they don't work properly, and in cases where the specified
				2044	default might not evaluate to the same value depending on
				2045	when it was evaluated. (For example, don't write <code>void
				2046	f(int n = counter++);</code>.)</p>
				2047
				2048	<p>In some other cases, default arguments can improve the
				2049	readability of their function declarations enough to
				2050	overcome the downsides above, so they are allowed. When in
				2051	doubt, use overloads.</p>
				2052	</div>
				2053
				2054	</div>
				2055
				2056	<h3 id="trailing_return">Trailing Return Type Syntax</h3>
				2057	<div class="summary">
				2058	<p>Use trailing return types only where using the ordinary syntax (leading
				2059	return types) is impractical or much less readable.</p>
				2060	</div>
				2061
				2062	<div class="definition">
				2063	<p>C++ allows two different forms of function declarations. In the older
				2064	form, the return type appears before the function name. For example:</p>
				2065	<pre>int foo(int x);
				2066	</pre>
				2067	<p>The new form, introduced in C++11, uses the <code>auto</code>
				2068	keyword before the function name and a trailing return type after
				2069	the argument list. For example, the declaration above could
				2070	equivalently be written:</p>
				2071	<pre>auto foo(int x) -> int;
				2072	</pre>
				2073	<p>The trailing return type is in the function's scope. This doesn't
				2074	make a difference for a simple case like <code>int</code> but it matters
				2075	for more complicated cases, like types declared in class scope or
				2076	types written in terms of the function parameters.</p>
				2077	</div>
				2078
				2079	<div class="stylebody">
				2080	<div class="pros">
				2081	<p>Trailing return types are the only way to explicitly specify the
				2082	return type of a <a href="#Lambda_expressions">lambda expression</a>.
				2083	In some cases the compiler is able to deduce a lambda's return type,
				2084	but not in all cases. Even when the compiler can deduce it automatically,
				2085	sometimes specifying it explicitly would be clearer for readers.
				2086	</p>
				2087	<p>Sometimes it's easier and more readable to specify a return type
				2088	after the function's parameter list has already appeared. This is
				2089	particularly true when the return type depends on template parameters.
				2090	For example:</p>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	2091	<pre> template <typename T, typename U>
				2092	auto add(T t, U u) -> decltype(t + u);
				2093	</pre>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2094	versus
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	2095	<pre> template <typename T, typename U>
				2096	decltype(declval<T&>() + declval<U&>()) add(T t, U u);
				2097	</pre>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2098	</div>
				2099
				2100	<div class="cons">
				2101	<p>Trailing return type syntax is relatively new and it has no
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	2102	analogue in C++-like languages such as C and Java, so some readers may
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2103	find it unfamiliar.</p>
				2104	<p>Existing code bases have an enormous number of function
				2105	declarations that aren't going to get changed to use the new syntax,
				2106	so the realistic choices are using the old syntax only or using a mixture
				2107	of the two. Using a single version is better for uniformity of style.</p>
				2108	</div>
				2109
				2110	<div class="decision">
				2111	<p>In most cases, continue to use the older style of function
				2112	declaration where the return type goes before the function name.
				2113	Use the new trailing-return-type form only in cases where it's
				2114	required (such as lambdas) or where, by putting the type after the
				2115	function's parameter list, it allows you to write the type in a much
				2116	more readable way. The latter case should be rare; it's mostly an
				2117	issue in fairly complicated template code, which is
				2118	<a href="#Template_metaprogramming">discouraged in most cases</a>.</p>
				2119
				2120	</div>
				2121	</div>
				2122
				2123	<h2 id="Google-Specific_Magic">Google-Specific Magic</h2>
				2124
				2125
				2126
				2127	<p>There are various tricks and utilities that
				2128	we use to make C++ code more robust, and various ways we use
				2129	C++ that may differ from what you see elsewhere.</p>
				2130
				2131
				2132
				2133	<h3 id="Ownership_and_Smart_Pointers">Ownership and Smart Pointers</h3>
				2134
				2135	<div class="summary">
				2136	<p>Prefer to have single, fixed owners for dynamically
				2137	allocated objects. Prefer to transfer ownership with smart
				2138	pointers.</p>
				2139	</div>
				2140
				2141	<div class="stylebody">
				2142
				2143	<div class="definition">
				2144	<p>"Ownership" is a bookkeeping technique for managing
				2145	dynamically allocated memory (and other resources). The
				2146	owner of a dynamically allocated object is an object or
				2147	function that is responsible for ensuring that it is
				2148	deleted when no longer needed. Ownership can sometimes be
				2149	shared, in which case the last owner is typically
				2150	responsible for deleting it. Even when ownership is not
				2151	shared, it can be transferred from one piece of code to
				2152	another.</p>
				2153
				2154	<p>"Smart" pointers are classes that act like pointers,
				2155	e.g. by overloading the <code>*</code> and
				2156	<code>-></code> operators. Some smart pointer types
				2157	can be used to automate ownership bookkeeping, to ensure
				2158	these responsibilities are met.
				2159	<a href="http://en.cppreference.com/w/cpp/memory/unique_ptr">
				2160	<code>std::unique_ptr</code></a> is a smart pointer type
				2161	introduced in C++11, which expresses exclusive ownership
				2162	of a dynamically allocated object; the object is deleted
				2163	when the <code>std::unique_ptr</code> goes out of scope.
				2164	It cannot be copied, but can be <em>moved</em> to
				2165	represent ownership transfer.
				2166	<a href="http://en.cppreference.com/w/cpp/memory/shared_ptr">
				2167	<code>std::shared_ptr</code></a> is a smart pointer type
				2168	that expresses shared ownership of
				2169	a dynamically allocated object. <code>std::shared_ptr</code>s
				2170	can be copied; ownership of the object is shared among
				2171	all copies, and the object is deleted when the last
				2172	<code>std::shared_ptr</code> is destroyed. </p>
				2173	</div>
				2174
				2175	<div class="pros">
				2176	<ul>
				2177	<li>It's virtually impossible to manage dynamically
				2178	allocated memory without some sort of ownership
				2179	logic.</li>
				2180
				2181	<li>Transferring ownership of an object can be cheaper
				2182	than copying it (if copying it is even possible).</li>
				2183
				2184	<li>Transferring ownership can be simpler than
				2185	'borrowing' a pointer or reference, because it reduces
				2186	the need to coordinate the lifetime of the object
				2187	between the two users.</li>
				2188
				2189	<li>Smart pointers can improve readability by making
				2190	ownership logic explicit, self-documenting, and
				2191	unambiguous.</li>
				2192
				2193	<li>Smart pointers can eliminate manual ownership
				2194	bookkeeping, simplifying the code and ruling out large
				2195	classes of errors.</li>
				2196
				2197	<li>For const objects, shared ownership can be a simple
				2198	and efficient alternative to deep copying.</li>
				2199	</ul>
				2200	</div>
				2201
				2202	<div class="cons">
				2203	<ul>
				2204	<li>Ownership must be represented and transferred via
				2205	pointers (whether smart or plain). Pointer semantics
				2206	are more complicated than value semantics, especially
				2207	in APIs: you have to worry not just about ownership,
				2208	but also aliasing, lifetime, and mutability, among
				2209	other issues.</li>
				2210
				2211	<li>The performance costs of value semantics are often
				2212	overestimated, so the performance benefits of ownership
				2213	transfer might not justify the readability and
				2214	complexity costs.</li>
				2215
				2216	<li>APIs that transfer ownership force their clients
				2217	into a single memory management model.</li>
				2218
				2219	<li>Code using smart pointers is less explicit about
				2220	where the resource releases take place.</li>
				2221
				2222	<li><code>std::unique_ptr</code> expresses ownership
				2223	transfer using C++11's move semantics, which are
				2224	relatively new and may confuse some programmers.</li>
				2225
				2226	<li>Shared ownership can be a tempting alternative to
				2227	careful ownership design, obfuscating the design of a
				2228	system.</li>
				2229
				2230	<li>Shared ownership requires explicit bookkeeping at
				2231	run-time, which can be costly.</li>
				2232
				2233	<li>In some cases (e.g. cyclic references), objects
				2234	with shared ownership may never be deleted.</li>
				2235
				2236	<li>Smart pointers are not perfect substitutes for
				2237	plain pointers.</li>
				2238	</ul>
				2239	</div>
				2240
				2241	<div class="decision">
				2242	<p>If dynamic allocation is necessary, prefer to keep
				2243	ownership with the code that allocated it. If other code
				2244	needs access to the object, consider passing it a copy,
				2245	or passing a pointer or reference without transferring
				2246	ownership. Prefer to use <code>std::unique_ptr</code> to
				2247	make ownership transfer explicit. For example:</p>
				2248
				2249	<pre>std::unique_ptr<Foo> FooFactory();
				2250	void FooConsumer(std::unique_ptr<Foo> ptr);
				2251	</pre>
				2252
				2253
				2254
				2255	<p>Do not design your code to use shared ownership
				2256	without a very good reason. One such reason is to avoid
				2257	expensive copy operations, but you should only do this if
				2258	the performance benefits are significant, and the
				2259	underlying object is immutable (i.e.
				2260	<code>std::shared_ptr<const Foo></code>). If you
				2261	do use shared ownership, prefer to use
				2262	<code>std::shared_ptr</code>.</p>
				2263
				2264	<p>Never use <code>std::auto_ptr</code>. Instead, use
				2265	<code>std::unique_ptr</code>.</p>
				2266	</div>
				2267
				2268	</div>
				2269
				2270	<h3 id="cpplint">cpplint</h3>
				2271
				2272	<div class="summary">
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	2273	<p>Use <code>cpplint.py</code> to detect style errors.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2274	</div>
				2275
				2276	<div class="stylebody">
				2277
				2278	<p><code>cpplint.py</code>
				2279	is a tool that reads a source file and identifies many
				2280	style errors. It is not perfect, and has both false
				2281	positives and false negatives, but it is still a valuable
				2282	tool. False positives can be ignored by putting <code>//
				2283	NOLINT</code> at the end of the line or
				2284	<code>// NOLINTNEXTLINE</code> in the previous line.</p>
				2285
				2286
				2287
				2288	<p>Some projects have instructions on
				2289	how to run <code>cpplint.py</code> from their project
				2290	tools. If the project you are contributing to does not,
				2291	you can download
				2292	<a href="https://raw.githubusercontent.com/google/styleguide/gh-pages/cpplint/cpplint.py">
				2293	<code>cpplint.py</code></a> separately.</p>
				2294
				2295	</div>
				2296
				2297
				2298
				2299	<h2 id="Other_C++_Features">Other C++ Features</h2>
				2300
				2301	<h3 id="Rvalue_references">Rvalue References</h3>
				2302
				2303	<div class="summary">
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	2304	<p>Use rvalue references to:</p>
				2305	<ul>
				2306	<li>Define move constructors and move assignment operators.</li>
				2307
				2308	<li>Define <a href="#Function_Overloading">overload sets</a> with
				2309	const& and && variants if you have evidence that this
				2310	provides meaningfully better performance than passing by value,
				2311	or if you're writing low-overhead generic code that needs to support
				2312	arbitrary types. Beware combinatorial overload sets, that is, seldom
				2313	overload more than one parameter.</li>
				2314
				2315	<li>Support 'perfect forwarding' in generic code.</li>
				2316	</ul>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2317	</div>
				2318
				2319	<div class="stylebody">
				2320
				2321	<div class="definition">
				2322	<p> Rvalue references
				2323	are a type of reference that can only bind to temporary
				2324	objects. The syntax is similar to traditional reference
				2325	syntax. For example, <code>void f(string&&
				2326	s);</code> declares a function whose argument is an
				2327	rvalue reference to a string.</p>
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	2328
				2329	<p id="Forwarding_references"> When the token '&&' is applied to
				2330	an unqualified template argument in a function
				2331	parameter, special template argument deduction
				2332	rules apply. Such a reference is called forwarding reference.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2333	</div>
				2334
				2335	<div class="pros">
				2336	<ul>
				2337	<li>Defining a move constructor (a constructor taking
				2338	an rvalue reference to the class type) makes it
				2339	possible to move a value instead of copying it. If
				2340	<code>v1</code> is a <code>std::vector<string></code>,
				2341	for example, then <code>auto v2(std::move(v1))</code>
				2342	will probably just result in some simple pointer
				2343	manipulation instead of copying a large amount of data.
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	2344	In many cases this can result in a major performance
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2345	improvement.</li>
				2346
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2347	<li>Rvalue references make it possible to implement
				2348	types that are movable but not copyable, which can be
				2349	useful for types that have no sensible definition of
				2350	copying but where you might still want to pass them as
				2351	function arguments, put them in containers, etc.</li>
				2352
				2353	<li><code>std::move</code> is necessary to make
				2354	effective use of some standard-library types, such as
				2355	<code>std::unique_ptr</code>.</li>
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	2356
				2357	<li><a href="#Forwarding_references">Forwarding references</a> which
				2358	use the rvalue reference token, make it possible to write a
				2359	generic function wrapper that forwards its arguments to
				2360	another function, and works whether or not its
				2361	arguments are temporary objects and/or const.
				2362	This is called 'perfect forwarding'.</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2363	</ul>
				2364	</div>
				2365
				2366	<div class="cons">
				2367	<ul>
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	2368	<li>Rvalue references are not yet widely
				2369	understood. Rules like automatic synthesis of move constructors and reference
				2370	collapsing (the latter refers to the special rules that apply to a T&&
				2371	parameter in a function template) are somewhat obscure.</li>
				2372
				2373	<li>Rvalue references are often misused. Using rvalue
				2374	references is counter-intuitive in signatures where the argument is expected
				2375	to have a valid specified state after the function call, or where no move
				2376	operation is performed.</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2377	</ul>
				2378	</div>
				2379
				2380	<div class="decision">
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	2381	<p>You may use rvalue references to define move constructors and move
				2382	assignment operators (as described in <a href="#Copyable_Movable_Types">Copyable and Movable Types</a>). See the <a href="primer#copying_moving">C++ Primer</a> for more information about
				2383	move semantics and <code>std::move</code>.</p>
				2384
				2385	<p>You may use rvalue references to define pairs of overloads, one taking
				2386	Foo&& and the other taking const Foo&. Usually the preferred
				2387	solution is just to pass by value, but an overloaded pair of functions
				2388	sometimes yields better performance and is sometimes necessary in generic code
				2389	that needs to support a wide variety of types. As always: if you're writing
				2390	more complicated code for the sake of performance, make sure you have evidence
				2391	that it actually helps.</p>
				2392
				2393	<p>You may use forwarding references in conjunction with <code><a href="http://en.cppreference.com/w/cpp/utility/forward">std::forward</a></code>,
				2394	to support perfect forwarding.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2395	</div>
				2396
				2397	</div>
				2398
				2399	<h3 id="Friends">Friends</h3>
				2400
				2401	<div class="summary">
				2402	<p>We allow use of <code>friend</code> classes and functions,
				2403	within reason.</p>
				2404	</div>
				2405
				2406	<div class="stylebody">
				2407
				2408	<p>Friends should usually be defined in the same file so
				2409	that the reader does not have to look in another file to
				2410	find uses of the private members of a class. A common use
				2411	of <code>friend</code> is to have a
				2412	<code>FooBuilder</code> class be a friend of
				2413	<code>Foo</code> so that it can construct the inner state
				2414	of <code>Foo</code> correctly, without exposing this
				2415	state to the world. In some cases it may be useful to
				2416	make a unittest class a friend of the class it tests.</p>
				2417
				2418	<p>Friends extend, but do not break, the encapsulation
				2419	boundary of a class. In some cases this is better than
				2420	making a member public when you want to give only one
				2421	other class access to it. However, most classes should
				2422	interact with other classes solely through their public
				2423	members.</p>
				2424
				2425	</div>
				2426
				2427	<h3 id="Exceptions">Exceptions</h3>
				2428
				2429	<div class="summary">
				2430	<p>We do not use C++ exceptions.</p>
				2431	</div>
				2432
				2433	<div class="stylebody">
				2434
				2435	<div class="pros">
				2436	<ul>
				2437	<li>Exceptions allow higher levels of an application to
				2438	decide how to handle "can't happen" failures in deeply
				2439	nested functions, without the obscuring and error-prone
				2440	bookkeeping of error codes.</li>
				2441
				2442
				2443
				2444	<li>Exceptions are used by most other
				2445	modern languages. Using them in C++ would make it more
				2446	consistent with Python, Java, and the C++ that others
				2447	are familiar with.</li>
				2448
				2449	<li>Some third-party C++ libraries use exceptions, and
				2450	turning them off internally makes it harder to
				2451	integrate with those libraries.</li>
				2452
				2453	<li>Exceptions are the only way for a constructor to
				2454	fail. We can simulate this with a factory function or
				2455	an <code>Init()</code> method, but these require heap
				2456	allocation or a new "invalid" state, respectively.</li>
				2457
				2458	<li>Exceptions are really handy in testing
				2459	frameworks.</li>
				2460	</ul>
				2461	</div>
				2462
				2463	<div class="cons">
				2464	<ul>
				2465	<li>When you add a <code>throw</code> statement to an
				2466	existing function, you must examine all of its
				2467	transitive callers. Either they must make at least the
				2468	basic exception safety guarantee, or they must never
				2469	catch the exception and be happy with the program
				2470	terminating as a result. For instance, if
				2471	<code>f()</code> calls <code>g()</code> calls
				2472	<code>h()</code>, and <code>h</code> throws an
				2473	exception that <code>f</code> catches, <code>g</code>
				2474	has to be careful or it may not clean up properly.</li>
				2475
				2476	<li>More generally, exceptions make the control flow of
				2477	programs difficult to evaluate by looking at code:
				2478	functions may return in places you don't expect. This
				2479	causes maintainability and debugging difficulties. You
				2480	can minimize this cost via some rules on how and where
				2481	exceptions can be used, but at the cost of more that a
				2482	developer needs to know and understand.</li>
				2483
				2484	<li>Exception safety requires both RAII and different
				2485	coding practices. Lots of supporting machinery is
				2486	needed to make writing correct exception-safe code
				2487	easy. Further, to avoid requiring readers to understand
				2488	the entire call graph, exception-safe code must isolate
				2489	logic that writes to persistent state into a "commit"
				2490	phase. This will have both benefits and costs (perhaps
				2491	where you're forced to obfuscate code to isolate the
				2492	commit). Allowing exceptions would force us to always
				2493	pay those costs even when they're not worth it.</li>
				2494
				2495	<li>Turning on exceptions adds data to each binary
				2496	produced, increasing compile time (probably slightly)
				2497	and possibly increasing address space pressure.
				2498	</li>
				2499
				2500	<li>The availability of exceptions may encourage
				2501	developers to throw them when they are not appropriate
				2502	or recover from them when it's not safe to do so. For
				2503	example, invalid user input should not cause exceptions
				2504	to be thrown. We would need to make the style guide
				2505	even longer to document these restrictions!</li>
				2506	</ul>
				2507	</div>
				2508
				2509	<div class="decision">
				2510	<p>On their face, the benefits of using exceptions
				2511	outweigh the costs, especially in new projects. However,
				2512	for existing code, the introduction of exceptions has
				2513	implications on all dependent code. If exceptions can be
				2514	propagated beyond a new project, it also becomes
				2515	problematic to integrate the new project into existing
				2516	exception-free code. Because most existing C++ code at
				2517	Google is not prepared to deal with exceptions, it is
				2518	comparatively difficult to adopt new code that generates
				2519	exceptions.</p>
				2520
				2521	<p>Given that Google's existing code is not
				2522	exception-tolerant, the costs of using exceptions are
				2523	somewhat greater than the costs in a new project. The
				2524	conversion process would be slow and error-prone. We
				2525	don't believe that the available alternatives to
				2526	exceptions, such as error codes and assertions, introduce
				2527	a significant burden. </p>
				2528
				2529	<p>Our advice against using exceptions is not predicated
				2530	on philosophical or moral grounds, but practical ones.
				2531	Because we'd like to use our open-source
				2532	projects at Google and it's difficult to do so if those
				2533	projects use exceptions, we need to advise against
				2534	exceptions in Google open-source projects as well.
				2535	Things would probably be different if we had to do it all
				2536	over again from scratch.</p>
				2537
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	2538	<p>This prohibition also applies to the exception handling related
				2539	features added in C++11, such as
				2540	<code>std::exception_ptr</code> and
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2541	<code>std::nested_exception</code>.</p>
				2542
				2543	<p>There is an <a href="#Windows_Code">exception</a> to
				2544	this rule (no pun intended) for Windows code.</p>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	2545
				2546	</div>
				2547
				2548	</div>
				2549
				2550	<h3 id="noexcept"><code>noexcept</code></h3>
				2551
				2552	<div class="summary">
				2553	<p>Specify <code>noexcept</code> when it is useful and correct.</p>
				2554	</div>
				2555
				2556	<div class="stylebody">
				2557	<div class="definition">
				2558	<p>The <code>noexcept</code> specifier is used to specify whether
				2559	a function will throw exceptions or not. If an exception
				2560	escapes from a function marked <code>noexcept</code>, the program
				2561	crashes via <code>std::terminate</code>.</p>
				2562
				2563	<p>The <code>noexcept</code> operator performs a compile-time
				2564	check that returns true if an expression is declared to not
				2565	throw any exceptions.</p>
				2566
				2567	</div>
				2568
				2569	<div class="pros">
				2570	<ul>
				2571	<li>Specifying move constructors as <code>noexcept</code>
				2572	improves performance in some cases, e.g.
				2573	<code>std::vector<T>::resize()</code> moves rather than
				2574	copies the objects if T's move constructor is
				2575	<code>noexcept</code>.</li>
				2576
				2577	<li>Specifying <code>noexcept</code> on a function can
				2578	trigger compiler optimizations in environments where
				2579	exceptions are enabled, e.g. compiler does not have to
				2580	generate extra code for stack-unwinding, if it knows
				2581	that no exceptions can be thrown due to a
				2582	<code>noexcept</code> specifier.</li>
				2583	</ul>
				2584	</div>
				2585
				2586	<div class="cons">
				2587	<ul>
				2588	<li>
				2589
				2590	In projects following this guide
				2591	that have exceptions disabled it is hard
				2592	to ensure that <code>noexcept</code>
				2593	specifiers are correct, and hard to define what
				2594	correctness even means.</li>
				2595
				2596	<li>It's hard, if not impossible, to undo <code>noexcept</code>
				2597	because it eliminates a guarantee that callers may be relying
				2598	on, in ways that are hard to detect.</li>
				2599	</ul>
				2600	</div>
				2601
				2602	<div class="decision">
				2603	<p>You may use <code>noexcept</code> when it is useful for
				2604	performance if it accurately reflects the intended semantics
				2605	of your function, i.e. that if an exception is somehow thrown
				2606	from within the function body then it represents a fatal error.
				2607	You can assume that <code>noexcept</code> on move constructors
				2608	has a meaningful performance benefit. If you think
				2609	there is significant performance benefit from specifying
				2610	<code>noexcept</code> on some other function, please discuss it
				2611	with
				2612	your project leads.</p>
				2613
				2614	<p>Prefer unconditional <code>noexcept</code> if exceptions are
				2615	completely disabled (i.e. most Google C++ environments).
				2616	Otherwise, use conditional <code>noexcept</code> specifiers
				2617	with simple conditions, in ways that evaluate false only in
				2618	the few cases where the function could potentially throw.
				2619	The tests might include type traits check on whether the
				2620	involved operation might throw (e.g.
				2621	<code>std::is_nothrow_move_constructible</code> for
				2622	move-constructing objects), or on whether allocation can throw
				2623	(e.g. <code>absl::default_allocator_is_nothrow</code> for
				2624	standard default allocation). Note in many cases the only
				2625	possible cause for an exception is allocation failure (we
				2626	believe move constructors should not throw except due to
				2627	allocation failure), and there are many applications where it’s
				2628	appropriate to treat memory exhaustion as a fatal error rather
				2629	than an exceptional condition that your program should attempt
				2630	to recover from. Even for other
				2631	potential failures you should prioritize interface simplicity
				2632	over supporting all possible exception throwing scenarios:
				2633	instead of writing a complicated <code>noexcept</code> clause
				2634	that depends on whether a hash function can throw, for example,
				2635	simply document that your component doesn’t support hash
				2636	functions throwing and make it unconditionally
				2637	<code>noexcept</code>.</p>
				2638
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2639	</div>
				2640
				2641	</div>
				2642
				2643	<h3 id="Run-Time_Type_Information__RTTI_">Run-Time Type
				2644	Information (RTTI)</h3>
				2645
				2646	<div class="summary">
				2647	<p>Avoid using Run Time Type Information (RTTI).</p>
				2648	</div>
				2649
				2650	<div class="stylebody">
				2651
				2652	<div class="definition">
				2653	<p> RTTI allows a
				2654	programmer to query the C++ class of an object at run
				2655	time. This is done by use of <code>typeid</code> or
				2656	<code>dynamic_cast</code>.</p>
				2657	</div>
				2658
				2659	<div class="cons">
				2660	<p>Querying the type of an object at run-time frequently
				2661	means a design problem. Needing to know the type of an
				2662	object at runtime is often an indication that the design
				2663	of your class hierarchy is flawed.</p>
				2664
				2665	<p>Undisciplined use of RTTI makes code hard to maintain.
				2666	It can lead to type-based decision trees or switch
				2667	statements scattered throughout the code, all of which
				2668	must be examined when making further changes.</p>
				2669	</div>
				2670
				2671	<div class="pros">
				2672	<p>The standard alternatives to RTTI (described below)
				2673	require modification or redesign of the class hierarchy
				2674	in question. Sometimes such modifications are infeasible
				2675	or undesirable, particularly in widely-used or mature
				2676	code.</p>
				2677
				2678	<p>RTTI can be useful in some unit tests. For example, it
				2679	is useful in tests of factory classes where the test has
				2680	to verify that a newly created object has the expected
				2681	dynamic type. It is also useful in managing the
				2682	relationship between objects and their mocks.</p>
				2683
				2684	<p>RTTI is useful when considering multiple abstract
				2685	objects. Consider</p>
				2686
				2687	<pre>bool Base::Equal(Base* other) = 0;
				2688	bool Derived::Equal(Base* other) {
				2689	Derived* that = dynamic_cast<Derived*>(other);
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	2690	if (that == nullptr)
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2691	return false;
				2692	...
				2693	}
				2694	</pre>
				2695	</div>
				2696
				2697	<div class="decision">
				2698	<p>RTTI has legitimate uses but is prone to abuse, so you
				2699	must be careful when using it. You may use it freely in
				2700	unittests, but avoid it when possible in other code. In
				2701	particular, think twice before using RTTI in new code. If
				2702	you find yourself needing to write code that behaves
				2703	differently based on the class of an object, consider one
				2704	of the following alternatives to querying the type:</p>
				2705
				2706	<ul>
				2707	<li>Virtual methods are the preferred way of executing
				2708	different code paths depending on a specific subclass
				2709	type. This puts the work within the object itself.</li>
				2710
				2711	<li>If the work belongs outside the object and instead
				2712	in some processing code, consider a double-dispatch
				2713	solution, such as the Visitor design pattern. This
				2714	allows a facility outside the object itself to
				2715	determine the type of class using the built-in type
				2716	system.</li>
				2717	</ul>
				2718
				2719	<p>When the logic of a program guarantees that a given
				2720	instance of a base class is in fact an instance of a
				2721	particular derived class, then a
				2722	<code>dynamic_cast</code> may be used freely on the
				2723	object. Usually one
				2724	can use a <code>static_cast</code> as an alternative in
				2725	such situations.</p>
				2726
				2727	<p>Decision trees based on type are a strong indication
				2728	that your code is on the wrong track.</p>
				2729
				2730	<pre class="badcode">if (typeid(*data) == typeid(D1)) {
				2731	...
				2732	} else if (typeid(*data) == typeid(D2)) {
				2733	...
				2734	} else if (typeid(*data) == typeid(D3)) {
				2735	...
				2736	</pre>
				2737
				2738	<p>Code such as this usually breaks when additional
				2739	subclasses are added to the class hierarchy. Moreover,
				2740	when properties of a subclass change, it is difficult to
				2741	find and modify all the affected code segments.</p>
				2742
				2743	<p>Do not hand-implement an RTTI-like workaround. The
				2744	arguments against RTTI apply just as much to workarounds
				2745	like class hierarchies with type tags. Moreover,
				2746	workarounds disguise your true intent.</p>
				2747	</div>
				2748
				2749	</div>
				2750
				2751	<h3 id="Casting">Casting</h3>
				2752
				2753	<div class="summary">
				2754	<p>Use C++-style casts
				2755	like <code>static_cast<float>(double_value)</code>, or brace
				2756	initialization for conversion of arithmetic types like
				2757	<code>int64 y = int64{1} << 42</code>. Do not use
				2758	cast formats like
				2759	<code>int y = (int)x</code> or <code>int y = int(x)</code> (but the latter
				2760	is okay when invoking a constructor of a class type).</p>
				2761	</div>
				2762
				2763	<div class="stylebody">
				2764
				2765	<div class="definition">
				2766	<p> C++ introduced a
				2767	different cast system from C that distinguishes the types
				2768	of cast operations.</p>
				2769	</div>
				2770
				2771	<div class="pros">
				2772	<p>The problem with C casts is the ambiguity of the operation;
				2773	sometimes you are doing a <em>conversion</em>
				2774	(e.g., <code>(int)3.5</code>) and sometimes you are doing
				2775	a <em>cast</em> (e.g., <code>(int)"hello"</code>). Brace
				2776	initialization and C++ casts can often help avoid this
				2777	ambiguity. Additionally, C++ casts are more visible when searching for
				2778	them.</p>
				2779	</div>
				2780
				2781	<div class="cons">
				2782	<p>The C++-style cast syntax is verbose and cumbersome.</p>
				2783	</div>
				2784
				2785	<div class="decision">
				2786	<p>Do not use C-style casts. Instead, use these C++-style casts when
				2787	explicit type conversion is necessary. </p>
				2788
				2789	<ul>
				2790	<li>Use brace initialization to convert arithmetic types
				2791	(e.g. <code>int64{x}</code>). This is the safest approach because code
				2792	will not compile if conversion can result in information loss. The
				2793	syntax is also concise.</li>
				2794
				2795
				2796
				2797	<li>Use <code>static_cast</code> as the equivalent of a C-style cast
				2798	that does value conversion, when you need to
				2799	explicitly up-cast a pointer from a class to its superclass, or when
				2800	you need to explicitly cast a pointer from a superclass to a
				2801	subclass. In this last case, you must be sure your object is
				2802	actually an instance of the subclass.</li>
				2803
				2804
				2805
				2806	<li>Use <code>const_cast</code> to remove the
				2807	<code>const</code> qualifier (see <a href="#Use_of_const">const</a>).</li>
				2808
				2809	<li>Use <code>reinterpret_cast</code> to do unsafe
				2810	conversions of pointer types to and from integer and
				2811	other pointer types. Use this only if you know what you
				2812	are doing and you understand the aliasing issues.
				2813	</li>
				2814
				2815
				2816	</ul>
				2817
				2818	<p>See the <a href="#Run-Time_Type_Information__RTTI_">
				2819	RTTI section</a> for guidance on the use of
				2820	<code>dynamic_cast</code>.</p>
				2821	</div>
				2822
				2823	</div>
				2824
				2825	<h3 id="Streams">Streams</h3>
				2826
				2827	<div class="summary">
				2828	<p>Use streams where appropriate, and stick to "simple"
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	2829	usages. Overload <code><<</code> for streaming only for types
				2830	representing values, and write only the user-visible value, not any
				2831	implementation details.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2832	</div>
				2833
				2834	<div class="stylebody">
				2835
				2836	<div class="definition">
				2837	<p>Streams are the standard I/O abstraction in C++, as
				2838	exemplified by the standard header <code><iostream></code>.
				2839	They are widely used in Google code, but only for debug logging
				2840	and test diagnostics.</p>
				2841	</div>
				2842
				2843	<div class="pros">
				2844	<p>The <code><<</code> and <code>>></code>
				2845	stream operators provide an API for formatted I/O that
				2846	is easily learned, portable, reusable, and extensible.
				2847	<code>printf</code>, by contrast, doesn't even support
				2848	<code>string</code>, to say nothing of user-defined types,
				2849	and is very difficult to use portably.
				2850	<code>printf</code> also obliges you to choose among the
				2851	numerous slightly different versions of that function,
				2852	and navigate the dozens of conversion specifiers.</p>
				2853
				2854	<p>Streams provide first-class support for console I/O
				2855	via <code>std::cin</code>, <code>std::cout</code>,
				2856	<code>std::cerr</code>, and <code>std::clog</code>.
				2857	The C APIs do as well, but are hampered by the need to
				2858	manually buffer the input. </p>
				2859	</div>
				2860
				2861	<div class="cons">
				2862	<ul>
				2863	<li>Stream formatting can be configured by mutating the
				2864	state of the stream. Such mutations are persistent, so
				2865	the behavior of your code can be affected by the entire
				2866	previous history of the stream, unless you go out of your
				2867	way to restore it to a known state every time other code
				2868	might have touched it. User code can not only modify the
				2869	built-in state, it can add new state variables and behaviors
				2870	through a registration system.</li>
				2871
				2872	<li>It is difficult to precisely control stream output, due
				2873	to the above issues, the way code and data are mixed in
				2874	streaming code, and the use of operator overloading (which
				2875	may select a different overload than you expect).</li>
				2876
				2877	<li>The practice of building up output through chains
				2878	of <code><<</code> operators interferes with
				2879	internationalization, because it bakes word order into the
				2880	code, and streams' support for localization is <a href="http://www.boost.org/doc/libs/1_48_0/libs/locale/doc/html/rationale.html#rationale_why">
				2881	flawed</a>.</li>
				2882
				2883
				2884
				2885
				2886
				2887	<li>The streams API is subtle and complex, so programmers must
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	2888	develop experience with it in order to use it effectively.</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2889
				2890	<li>Resolving the many overloads of <code><<</code> is
				2891	extremely costly for the compiler. When used pervasively in a
				2892	large code base, it can consume as much as 20% of the parsing
				2893	and semantic analysis time.</li>
				2894	</ul>
				2895	</div>
				2896
				2897	<div class="decision">
				2898	<p>Use streams only when they are the best tool for the job.
				2899	This is typically the case when the I/O is ad-hoc, local,
				2900	human-readable, and targeted at other developers rather than
				2901	end-users. Be consistent with the code around you, and with the
				2902	codebase as a whole; if there's an established tool for
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	2903	your problem, use that tool instead.
				2904	In particular,
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	2905
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	2906	logging libraries are usually a better
				2907	choice than <code>std::cerr</code> or <code>std::clog</code>
				2908	for diagnostic output, and the libraries in
				2909
				2910	<code>absl/strings</code>
				2911	or the equivalent are usually a
				2912	better choice than <code>std::stringstream</code>.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2913
				2914	<p>Avoid using streams for I/O that faces external users or
				2915	handles untrusted data. Instead, find and use the appropriate
				2916	templating libraries to handle issues like internationalization,
				2917	localization, and security hardening.</p>
				2918
				2919	<p>If you do use streams, avoid the stateful parts of the
				2920	streams API (other than error state), such as <code>imbue()</code>,
				2921	<code>xalloc()</code>, and <code>register_callback()</code>.
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	2922	Use explicit formatting functions (see e.g.
				2923
				2924	<code>absl/strings</code>)
				2925	rather than
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	2926	stream manipulators or formatting flags to control formatting
				2927	details such as number base, precision, or padding.</p>
				2928
				2929	<p>Overload <code><<</code> as a streaming operator
				2930	for your type only if your type represents a value, and
				2931	<code><<</code> writes out a human-readable string
				2932	representation of that value. Avoid exposing implementation
				2933	details in the output of <code><<</code>; if you need to print
				2934	object internals for debugging, use named functions instead
				2935	(a method named <code>DebugString()</code> is the most common
				2936	convention).</p>
				2937	</div>
				2938
				2939	</div>
				2940
				2941	<h3 id="Preincrement_and_Predecrement">Preincrement and Predecrement</h3>
				2942
				2943	<div class="summary">
				2944	<p>Use prefix form (<code>++i</code>) of the increment and
				2945	decrement operators with iterators and other template
				2946	objects.</p>
				2947	</div>
				2948
				2949	<div class="stylebody">
				2950
				2951	<div class="definition">
				2952	<p> When a variable
				2953	is incremented (<code>++i</code> or <code>i++</code>) or
				2954	decremented (<code>--i</code> or <code>i--</code>) and
				2955	the value of the expression is not used, one must decide
				2956	whether to preincrement (decrement) or postincrement
				2957	(decrement).</p>
				2958	</div>
				2959
				2960	<div class="pros">
				2961	<p>When the return value is ignored, the "pre" form
				2962	(<code>++i</code>) is never less efficient than the
				2963	"post" form (<code>i++</code>), and is often more
				2964	efficient. This is because post-increment (or decrement)
				2965	requires a copy of <code>i</code> to be made, which is
				2966	the value of the expression. If <code>i</code> is an
				2967	iterator or other non-scalar type, copying <code>i</code>
				2968	could be expensive. Since the two types of increment
				2969	behave the same when the value is ignored, why not just
				2970	always pre-increment?</p>
				2971	</div>
				2972
				2973	<div class="cons">
				2974	<p>The tradition developed, in C, of using post-increment
				2975	when the expression value is not used, especially in
				2976	<code>for</code> loops. Some find post-increment easier
				2977	to read, since the "subject" (<code>i</code>) precedes
				2978	the "verb" (<code>++</code>), just like in English.</p>
				2979	</div>
				2980
				2981	<div class="decision">
				2982	<p> For simple scalar
				2983	(non-object) values there is no reason to prefer one form
				2984	and we allow either. For iterators and other template
				2985	types, use pre-increment.</p>
				2986	</div>
				2987
				2988	</div>
				2989
				2990	<h3 id="Use_of_const">Use of const</h3>
				2991
				2992	<div class="summary">
				2993	<p>Use <code>const</code> whenever it makes sense. With C++11,
				2994	<code>constexpr</code> is a better choice for some uses of
				2995	const.</p>
				2996	</div>
				2997
				2998	<div class="stylebody">
				2999
				3000	<div class="definition">
				3001	<p> Declared variables and parameters can be preceded
				3002	by the keyword <code>const</code> to indicate the variables
				3003	are not changed (e.g., <code>const int foo</code>). Class
				3004	functions can have the <code>const</code> qualifier to
				3005	indicate the function does not change the state of the
				3006	class member variables (e.g., <code>class Foo { int
				3007	Bar(char c) const; };</code>).</p>
				3008	</div>
				3009
				3010	<div class="pros">
				3011	<p>Easier for people to understand how variables are being
				3012	used. Allows the compiler to do better type checking,
				3013	and, conceivably, generate better code. Helps people
				3014	convince themselves of program correctness because they
				3015	know the functions they call are limited in how they can
				3016	modify your variables. Helps people know what functions
				3017	are safe to use without locks in multi-threaded
				3018	programs.</p>
				3019	</div>
				3020
				3021	<div class="cons">
				3022	<p><code>const</code> is viral: if you pass a
				3023	<code>const</code> variable to a function, that function
				3024	must have <code>const</code> in its prototype (or the
				3025	variable will need a <code>const_cast</code>). This can
				3026	be a particular problem when calling library
				3027	functions.</p>
				3028	</div>
				3029
				3030	<div class="decision">
				3031	<p><code>const</code> variables, data members, methods
				3032	and arguments add a level of compile-time type checking;
				3033	it is better to detect errors as soon as possible.
				3034	Therefore we strongly recommend that you use
				3035	<code>const</code> whenever it makes sense to do so:</p>
				3036
				3037	<ul>
				3038	<li>If a function guarantees that it will not modify an argument
				3039	passed by reference or by pointer, the corresponding function parameter
				3040	should be a reference-to-const (<code>const T&</code>) or
				3041	pointer-to-const (<code>const T*</code>), respectively.</li>
				3042
				3043	<li>Declare methods to be <code>const</code> whenever
				3044	possible. Accessors should almost always be
				3045	<code>const</code>. Other methods should be const if
				3046	they do not modify any data members, do not call any
				3047	non-<code>const</code> methods, and do not return a
				3048	non-<code>const</code> pointer or
				3049	non-<code>const</code> reference to a data member.</li>
				3050
				3051	<li>Consider making data members <code>const</code>
				3052	whenever they do not need to be modified after
				3053	construction.</li>
				3054	</ul>
				3055
				3056	<p>The <code>mutable</code> keyword is allowed but is
				3057	unsafe when used with threads, so thread safety should be
				3058	carefully considered first.</p>
				3059	</div>
				3060
				3061	<div class="stylepoint_subsection">
				3062	<h4>Where to put the const</h4>
				3063
				3064	<p>Some people favor the form <code>int const *foo</code>
				3065	to <code>const int* foo</code>. They argue that this is
				3066	more readable because it's more consistent: it keeps the
				3067	rule that <code>const</code> always follows the object
				3068	it's describing. However, this consistency argument
				3069	doesn't apply in codebases with few deeply-nested pointer
				3070	expressions since most <code>const</code> expressions
				3071	have only one <code>const</code>, and it applies to the
				3072	underlying value. In such cases, there's no consistency
				3073	to maintain. Putting the <code>const</code> first is
				3074	arguably more readable, since it follows English in
				3075	putting the "adjective" (<code>const</code>) before the
				3076	"noun" (<code>int</code>).</p>
				3077
				3078	<p>That said, while we encourage putting
				3079	<code>const</code> first, we do not require it. But be
				3080	consistent with the code around you!</p>
				3081	</div>
				3082
				3083	</div>
				3084
				3085	<h3 id="Use_of_constexpr">Use of constexpr</h3>
				3086
				3087	<div class="summary">
				3088	<p>In C++11, use <code>constexpr</code> to define true
				3089	constants or to ensure constant initialization.</p>
				3090	</div>
				3091
				3092	<div class="stylebody">
				3093
				3094	<div class="definition">
				3095	<p> Some variables can be declared <code>constexpr</code>
				3096	to indicate the variables are true constants, i.e. fixed at
				3097	compilation/link time. Some functions and constructors
				3098	can be declared <code>constexpr</code> which enables them
				3099	to be used in defining a <code>constexpr</code>
				3100	variable.</p>
				3101	</div>
				3102
				3103	<div class="pros">
				3104	<p>Use of <code>constexpr</code> enables definition of
				3105	constants with floating-point expressions rather than
				3106	just literals; definition of constants of user-defined
				3107	types; and definition of constants with function
				3108	calls.</p>
				3109	</div>
				3110
				3111	<div class="cons">
				3112	<p>Prematurely marking something as constexpr may cause
				3113	migration problems if later on it has to be downgraded.
				3114	Current restrictions on what is allowed in constexpr
				3115	functions and constructors may invite obscure workarounds
				3116	in these definitions.</p>
				3117	</div>
				3118
				3119	<div class="decision">
				3120	<p><code>constexpr</code> definitions enable a more
				3121	robust specification of the constant parts of an
				3122	interface. Use <code>constexpr</code> to specify true
				3123	constants and the functions that support their
				3124	definitions. Avoid complexifying function definitions to
				3125	enable their use with <code>constexpr</code>. Do not use
				3126	<code>constexpr</code> to force inlining.</p>
				3127	</div>
				3128
				3129	</div>
				3130
				3131	<h3 id="Integer_Types">Integer Types</h3>
				3132
				3133	<div class="summary">
				3134	<p>Of the built-in C++ integer types, the only one used
				3135	is
				3136	<code>int</code>. If a program needs a variable of a
				3137	different size, use
				3138	a precise-width integer type from
				3139	<code><stdint.h></code>, such as
				3140	<code>int16_t</code>. If your variable represents a
				3141	value that could ever be greater than or equal to 2^31
				3142	(2GiB), use a 64-bit type such as
				3143	<code>int64_t</code>.
				3144	Keep in mind that even if your value won't ever be too large
				3145	for an <code>int</code>, it may be used in intermediate
				3146	calculations which may require a larger type. When in doubt,
				3147	choose a larger type.</p>
				3148	</div>
				3149
				3150	<div class="stylebody">
				3151
				3152	<div class="definition">
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3153	<p> C++ does not specify the sizes of integer types
				3154	like <code>int</code>. Typically people assume
				3155	that <code>short</code> is 16 bits,
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3156	<code>int</code> is 32 bits, <code>long</code> is 32 bits
				3157	and <code>long long</code> is 64 bits.</p>
				3158	</div>
				3159
				3160	<div class="pros">
				3161	<p>Uniformity of declaration.</p>
				3162	</div>
				3163
				3164	<div class="cons">
				3165	<p>The sizes of integral types in C++ can vary based on
				3166	compiler and architecture.</p>
				3167	</div>
				3168
				3169	<div class="decision">
				3170
				3171	<p>
				3172	<code><stdint.h></code> defines types
				3173	like <code>int16_t</code>, <code>uint32_t</code>,
				3174	<code>int64_t</code>, etc. You should always use
				3175	those in preference to <code>short</code>, <code>unsigned
				3176	long long</code> and the like, when you need a guarantee
				3177	on the size of an integer. Of the C integer types, only
				3178	<code>int</code> should be used. When appropriate, you
				3179	are welcome to use standard types like
				3180	<code>size_t</code> and <code>ptrdiff_t</code>.</p>
				3181
				3182	<p>We use <code>int</code> very often, for integers we
				3183	know are not going to be too big, e.g., loop counters.
				3184	Use plain old <code>int</code> for such things. You
				3185	should assume that an <code>int</code> is
				3186
				3187	at least 32 bits, but don't
				3188	assume that it has more than 32 bits. If you need a 64-bit
				3189	integer type, use
				3190	<code>int64_t</code>
				3191	or
				3192	<code>uint64_t</code>.</p>
				3193
				3194	<p>For integers we know can be "big",
				3195	use
				3196	<code>int64_t</code>.
				3197	</p>
				3198
				3199	<p>You should not use the unsigned integer types such as
				3200	<code>uint32_t</code>, unless there is a valid
				3201	reason such as representing a bit pattern rather than a
				3202	number, or you need defined overflow modulo 2^N. In
				3203	particular, do not use unsigned types to say a number
				3204	will never be negative. Instead, use
				3205	assertions for this.</p>
				3206
				3207
				3208
				3209	<p>If your code is a container that returns a size, be
				3210	sure to use a type that will accommodate any possible
				3211	usage of your container. When in doubt, use a larger type
				3212	rather than a smaller type.</p>
				3213
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3214	<p>Use care when converting integer types. Integer conversions and
				3215	promotions can cause undefined behavior, leading to security bugs and
				3216	other problems.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3217	</div>
				3218
				3219	<div class="stylepoint_subsection">
				3220
				3221	<h4>On Unsigned Integers</h4>
				3222
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3223	<p>Unsigned integers are good for representing bitfields and modular
				3224	arithmetic. Because of historical accident, the C++ standard also uses
				3225	unsigned integers to represent the size of containers - many members
				3226	of the standards body believe this to be a mistake, but it is
				3227	effectively impossible to fix at this point. The fact that unsigned
				3228	arithmetic doesn't model the behavior of a simple integer, but is
				3229	instead defined by the standard to model modular arithmetic (wrapping
				3230	around on overflow/underflow), means that a significant class of bugs
				3231	cannot be diagnosed by the compiler. In other cases, the defined
				3232	behavior impedes optimization.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3233
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3234	<p>That said, mixing signedness of integer types is responsible for an
				3235	equally large class of problems. The best advice we can provide: try
				3236	to use iterators and containers rather than pointers and sizes, try
				3237	not to mix signedness, and try to avoid unsigned types (except for
				3238	representing bitfields or modular arithmetic). Do not use an unsigned
				3239	type merely to assert that a variable is non-negative.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3240	</div>
				3241
				3242	</div>
				3243
				3244	<h3 id="64-bit_Portability">64-bit Portability</h3>
				3245
				3246	<div class="summary">
				3247	<p>Code should be 64-bit and 32-bit friendly. Bear in mind
				3248	problems of printing, comparisons, and structure alignment.</p>
				3249	</div>
				3250
				3251	<div class="stylebody">
				3252
				3253	<ul>
				3254	<li>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3255	<p>Correct portable <code>printf()</code> conversion specifiers for
				3256	some integral typedefs rely on macro expansions that we find unpleasant to
				3257	use and impractical to require (the <code>PRI</code> macros from
				3258	<code><cinttypes></code>). Unless there is no reasonable alternative
				3259	for your particular case, try to avoid or even upgrade APIs that rely on the
				3260	<code>printf</code> family. Instead use a library supporting typesafe numeric
				3261	formatting, such as
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	3262
				3263	<a href="https://github.com/abseil/abseil-cpp/blob/master/absl/strings/str_cat.h"><code>StrCat</code></a>
				3264	or
				3265
				3266	<a href="https://github.com/abseil/abseil-cpp/blob/master/absl/strings/substitute.h"><code>Substitute</code></a>
				3267	for fast simple conversions,
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3268
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	3269	or <a href="#Streams"><code>std::ostream</code></a>.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3270
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3271	<p>Unfortunately, the <code>PRI</code> macros are the only portable way to
				3272	specify a conversion for the standard bitwidth typedefs (e.g.
				3273	<code>int64_t</code>, <code>uint64_t</code>, <code>int32_t</code>,
				3274	<code>uint32_t</code>, etc).
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3275
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3276	Where possible, avoid passing arguments of types specified by bitwidth
				3277	typedefs to <code>printf</code>-based APIs. Note that it is acceptable
				3278	to use typedefs for which printf has dedicated length modifiers, such as
				3279	<code>size_t</code> (<code>z</code>),
				3280	<code>ptrdiff_t</code> (<code>t</code>), and
				3281	<code>maxint_t</code> (<code>j</code>).</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3282	</li>
				3283
				3284	<li>Remember that <code>sizeof(void *)</code> !=
				3285	<code>sizeof(int)</code>. Use <code>intptr_t</code> if
				3286	you want a pointer-sized integer.</li>
				3287
				3288	<li>You may need to be careful with structure
				3289	alignments, particularly for structures being stored on
				3290	disk. Any class/structure with a
				3291	<code>int64_t</code>/<code>uint64_t</code>
				3292	member will by default end up being 8-byte aligned on a
				3293	64-bit system. If you have such structures being shared
				3294	on disk between 32-bit and 64-bit code, you will need
				3295	to ensure that they are packed the same on both
				3296	architectures.
				3297	Most compilers offer a way to
				3298	alter structure alignment. For gcc, you can use
				3299	<code>__attribute__((packed))</code>. MSVC offers
				3300	<code>#pragma pack()</code> and
				3301	<code>__declspec(align())</code>.</li>
				3302
				3303	<li>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3304	<p>Use <a href="#Casting">braced-initialization</a> as needed to create
				3305	64-bit constants. For example:</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3306
				3307
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3308	<pre>int64_t my_value{0x123456789};
				3309	uint64_t my_mask{3ULL << 48};
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3310	</pre>
				3311	</li>
				3312	</ul>
				3313
				3314	</div>
				3315
				3316	<h3 id="Preprocessor_Macros">Preprocessor Macros</h3>
				3317
				3318	<div class="summary">
				3319	<p>Avoid defining macros, especially in headers; prefer
				3320	inline functions, enums, and <code>const</code> variables.
				3321	Name macros with a project-specific prefix. Do not use
				3322	macros to define pieces of a C++ API.</p>
				3323	</div>
				3324
				3325	<div class="stylebody">
				3326
				3327	<p>Macros mean that the code you see is not the same as
				3328	the code the compiler sees. This can introduce unexpected
				3329	behavior, especially since macros have global scope.</p>
				3330
				3331	<p>The problems introduced by macros are especially severe
				3332	when they are used to define pieces of a C++ API,
				3333	and still more so for public APIs. Every error message from
				3334	the compiler when developers incorrectly use that interface
				3335	now must explain how the macros formed the interface.
				3336	Refactoring and analysis tools have a dramatically harder
				3337	time updating the interface. As a consequence, we
				3338	specifically disallow using macros in this way.
				3339	For example, avoid patterns like:</p>
				3340
				3341	<pre class="badcode">class WOMBAT_TYPE(Foo) {
				3342	// ...
				3343
				3344	public:
				3345	EXPAND_PUBLIC_WOMBAT_API(Foo)
				3346
				3347	EXPAND_WOMBAT_COMPARISONS(Foo, ==, <)
				3348	};
				3349	</pre>
				3350
				3351	<p>Luckily, macros are not nearly as necessary in C++ as
				3352	they are in C. Instead of using a macro to inline
				3353	performance-critical code, use an inline function.
				3354	Instead of using a macro to store a constant, use a
				3355	<code>const</code> variable. Instead of using a macro to
				3356	"abbreviate" a long variable name, use a reference.
				3357	Instead of using a macro to conditionally compile code
				3358	... well, don't do that at all (except, of course, for
				3359	the <code>#define</code> guards to prevent double
				3360	inclusion of header files). It makes testing much more
				3361	difficult.</p>
				3362
				3363	<p>Macros can do things these other techniques cannot,
				3364	and you do see them in the codebase, especially in the
				3365	lower-level libraries. And some of their special features
				3366	(like stringifying, concatenation, and so forth) are not
				3367	available through the language proper. But before using a
				3368	macro, consider carefully whether there's a non-macro way
				3369	to achieve the same result. If you need to use a macro to
				3370	define an interface, contact
				3371	your project leads to request
				3372	a waiver of this rule.</p>
				3373
				3374	<p>The following usage pattern will avoid many problems
				3375	with macros; if you use macros, follow it whenever
				3376	possible:</p>
				3377
				3378	<ul>
				3379	<li>Don't define macros in a <code>.h</code> file.</li>
				3380
				3381	<li><code>#define</code> macros right before you use
				3382	them, and <code>#undef</code> them right after.</li>
				3383
				3384	<li>Do not just <code>#undef</code> an existing macro
				3385	before replacing it with your own; instead, pick a name
				3386	that's likely to be unique.</li>
				3387
				3388	<li>Try not to use macros that expand to unbalanced C++
				3389	constructs, or at least document that behavior
				3390	well.</li>
				3391
				3392	<li>Prefer not using <code>##</code> to generate
				3393	function/class/variable names.</li>
				3394	</ul>
				3395
				3396	<p>Exporting macros from headers (i.e. defining them in a header
				3397	without <code>#undef</code>ing them before the end of the header)
				3398	is extremely strongly discouraged. If you do export a macro from a
				3399	header, it must have a globally unique name. To achieve this, it
				3400	must be named with a prefix consisting of your project's namespace
				3401	name (but upper case). </p>
				3402
				3403	</div>
				3404
				3405	<h3 id="0_and_nullptr/NULL">0 and nullptr/NULL</h3>
				3406
				3407	<div class="summary">
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3408	<p>Use <code>0</code> for integers, <code>0.0</code> for reals,
				3409	<code>nullptr</code> for pointers, and <code>'\0'</code> for chars.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3410	</div>
				3411
				3412	<div class="stylebody">
				3413
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3414	<p>Use <code>0</code> for integers and <code>0.0</code> for reals.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3415
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	3416	<p>For pointers (address values), use <code>nullptr</code>, as this
				3417	provides type-safety.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3418
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3419	<p>For C++03 projects, prefer <code>NULL</code> to <code>0</code>. While the
				3420	values are equivalent, <code>NULL</code> looks more like a pointer to the
				3421	reader, and some C++ compilers provide special definitions of <code>NULL</code>
				3422	which enable them to give useful warnings.</p>
				3423
				3424	<p>Use <code>'\0'</code> for the null character. Using the correct type makes
				3425	the code more readable.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3426
				3427	</div>
				3428
				3429	<h3 id="sizeof">sizeof</h3>
				3430
				3431	<div class="summary">
				3432	<p>Prefer <code>sizeof(<var>varname</var>)</code> to
				3433	<code>sizeof(<var>type</var>)</code>.</p>
				3434	</div>
				3435
				3436	<div class="stylebody">
				3437
				3438	<p>Use <code>sizeof(<var>varname</var>)</code> when you
				3439	take the size of a particular variable.
				3440	<code>sizeof(<var>varname</var>)</code> will update
				3441	appropriately if someone changes the variable type either
				3442	now or later. You may use
				3443	<code>sizeof(<var>type</var>)</code> for code unrelated
				3444	to any particular variable, such as code that manages an
				3445	external or internal data format where a variable of an
				3446	appropriate C++ type is not convenient.</p>
				3447
				3448	<pre>Struct data;
				3449	memset(&data, 0, sizeof(data));
				3450	</pre>
				3451
				3452	<pre class="badcode">memset(&data, 0, sizeof(Struct));
				3453	</pre>
				3454
				3455	<pre>if (raw_size < sizeof(int)) {
				3456	LOG(ERROR) << "compressed record not big enough for count: " << raw_size;
				3457	return false;
				3458	}
				3459	</pre>
				3460
				3461	</div>
				3462
				3463	<h3 id="auto">auto</h3>
				3464
				3465	<div class="summary">
				3466	<p>Use <code>auto</code> to avoid type names that are noisy, obvious,
				3467	or unimportant - cases where the type doesn't aid in clarity for the
				3468	reader. Continue to use manifest type declarations when it helps
				3469	readability.</p>
				3470	</div>
				3471
				3472	<div class="stylebody">
				3473
				3474	<div class="pros">
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3475
				3476	<ul>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3477	<li>C++ type names can be long and cumbersome, especially when they
				3478	involve templates or namespaces.</li>
				3479	<li>When a C++ type name is repeated within a single declaration or a
				3480	small code region, the repetition may not be aiding readability.</li>
				3481	<li>It is sometimes safer to let the type be specified by the type of
				3482	the initialization expression, since that avoids the possibility of
				3483	unintended copies or type conversions.</li>
				3484	</ul>
				3485	</div>
				3486	<div class="cons">
				3487
				3488	<p>Sometimes code is clearer when types are manifest,
				3489	especially when a variable's initialization depends on
				3490	things that were declared far away. In expressions
				3491	like:</p>
				3492
				3493	<pre class="badcode">auto foo = x.add_foo();
				3494	auto i = y.Find(key);
				3495	</pre>
				3496
				3497	<p>it may not be obvious what the resulting types are if the type
				3498	of <code>y</code> isn't very well known, or if <code>y</code> was
				3499	declared many lines earlier.</p>
				3500
				3501	<p>Programmers have to understand the difference between
				3502	<code>auto</code> and <code>const auto&</code> or
				3503	they'll get copies when they didn't mean to.</p>
				3504
				3505	<p>If an <code>auto</code> variable is used as part of an
				3506	interface, e.g. as a constant in a header, then a
				3507	programmer might change its type while only intending to
				3508	change its value, leading to a more radical API change
				3509	than intended.</p>
				3510	</div>
				3511
				3512	<div class="decision">
				3513
				3514	<p><code>auto</code> is permitted when it increases readability,
				3515	particularly as described below. Never initialize an <code>auto</code>-typed
				3516	variable with a braced initializer list.</p>
				3517
				3518	<p>Specific cases where <code>auto</code> is allowed or encouraged:
				3519	</p><ul>
				3520	<li>(Encouraged) For iterators and other long/cluttery type names, particularly
				3521	when the type is clear from context (calls
				3522	to <code>find</code>, <code>begin</code>, or <code>end</code> for
				3523	instance).</li>
				3524	<li>(Allowed) When the type is clear from local context (in the same expression
				3525	or within a few lines). Initialization of a pointer or smart pointer
				3526	with calls
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	3527	to <code>new</code> and
				3528	<code>std::make_unique</code>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3529	commonly falls into this category, as does use of <code>auto</code> in
				3530	a range-based loop over a container whose type is spelled out
				3531	nearby.</li>
				3532	<li>(Allowed) When the type doesn't matter because it isn't being used for
				3533	anything other than equality comparison.</li>
				3534	<li>(Encouraged) When iterating over a map with a range-based loop
				3535	(because it is often assumed that the correct type
				3536	is <code>std::pair<KeyType, ValueType></code> whereas it is actually
				3537	<code>std::pair<const KeyType, ValueType></code>). This is
				3538	particularly well paired with local <code>key</code>
				3539	and <code>value</code> aliases for <code>.first</code>
				3540	and <code>.second</code> (often const-ref).
				3541	<pre class="code">for (const auto& item : some_map) {
				3542	const KeyType& key = item.first;
				3543	const ValType& value = item.second;
				3544	// The rest of the loop can now just refer to key and value,
				3545	// a reader can see the types in question, and we've avoided
				3546	// the too-common case of extra copies in this iteration.
				3547	}
				3548	</pre>
				3549	</li>
				3550	</ul>
				3551
				3552	</div>
				3553
				3554	</div>
				3555
				3556	<h3 id="Braced_Initializer_List">Braced Initializer List</h3>
				3557
				3558	<div class="summary">
				3559	<p>You may use braced initializer lists.</p>
				3560	</div>
				3561
				3562	<div class="stylebody">
				3563
				3564	<p>In C++03, aggregate types (arrays and structs with no
				3565	constructor) could be initialized with braced initializer lists.</p>
				3566
				3567	<pre>struct Point { int x; int y; };
				3568	Point p = {1, 2};
				3569	</pre>
				3570
				3571	<p>In C++11, this syntax was generalized, and any object type can now
				3572	be created with a braced initializer list, known as a
				3573	<i>braced-init-list</i> in the C++ grammar. Here are a few examples
				3574	of its use.</p>
				3575
				3576	<pre>// Vector takes a braced-init-list of elements.
				3577	std::vector<string> v{"foo", "bar"};
				3578
				3579	// Basically the same, ignoring some small technicalities.
				3580	// You may choose to use either form.
				3581	std::vector<string> v = {"foo", "bar"};
				3582
				3583	// Usable with 'new' expressions.
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	3584	auto p = new std::vector<string>{"foo", "bar"};
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3585
				3586	// A map can take a list of pairs. Nested braced-init-lists work.
				3587	std::map<int, string> m = {{1, "one"}, {2, "2"}};
				3588
				3589	// A braced-init-list can be implicitly converted to a return type.
				3590	std::vector<int> test_function() { return {1, 2, 3}; }
				3591
				3592	// Iterate over a braced-init-list.
				3593	for (int i : {-1, -2, -3}) {}
				3594
				3595	// Call a function using a braced-init-list.
				3596	void TestFunction2(std::vector<int> v) {}
				3597	TestFunction2({1, 2, 3});
				3598	</pre>
				3599
				3600	<p>A user-defined type can also define a constructor and/or assignment operator
				3601	that take <code>std::initializer_list<T></code>, which is automatically
				3602	created from <i>braced-init-list</i>:</p>
				3603
				3604	<pre>class MyType {
				3605	public:
				3606	// std::initializer_list references the underlying init list.
				3607	// It should be passed by value.
				3608	MyType(std::initializer_list<int> init_list) {
				3609	for (int i : init_list) append(i);
				3610	}
				3611	MyType& operator=(std::initializer_list<int> init_list) {
				3612	clear();
				3613	for (int i : init_list) append(i);
				3614	}
				3615	};
				3616	MyType m{2, 3, 5, 7};
				3617	</pre>
				3618
				3619	<p>Finally, brace initialization can also call ordinary
				3620	constructors of data types, even if they do not have
				3621	<code>std::initializer_list<T></code> constructors.</p>
				3622
				3623	<pre>double d{1.23};
				3624	// Calls ordinary constructor as long as MyOtherType has no
				3625	// std::initializer_list constructor.
				3626	class MyOtherType {
				3627	public:
				3628	explicit MyOtherType(string);
				3629	MyOtherType(int, string);
				3630	};
				3631	MyOtherType m = {1, "b"};
				3632	// If the constructor is explicit, you can't use the "= {}" form.
				3633	MyOtherType m{"b"};
				3634	</pre>
				3635
				3636	<p>Never assign a <i>braced-init-list</i> to an auto
				3637	local variable. In the single element case, what this
				3638	means can be confusing.</p>
				3639
				3640	<pre class="badcode">auto d = {1.23}; // d is a std::initializer_list<double>
				3641	</pre>
				3642
				3643	<pre>auto d = double{1.23}; // Good -- d is a double, not a std::initializer_list.
				3644	</pre>
				3645
				3646	<p>See <a href="#Braced_Initializer_List_Format">Braced_Initializer_List_Format</a> for formatting.</p>
				3647
				3648	</div>
				3649
				3650	<h3 id="Lambda_expressions">Lambda expressions</h3>
				3651
				3652	<div class="summary">
				3653	<p>Use lambda expressions where appropriate. Prefer explicit captures
				3654	when the lambda will escape the current scope.</p>
				3655	</div>
				3656
				3657	<div class="stylebody">
				3658
				3659	<div class="definition">
				3660
				3661	<p> Lambda expressions are a concise way of creating anonymous
				3662	function objects. They're often useful when passing
				3663	functions as arguments. For example:</p>
				3664
				3665	<pre>std::sort(v.begin(), v.end(), [](int x, int y) {
				3666	return Weight(x) < Weight(y);
				3667	});
				3668	</pre>
				3669
				3670	<p> They further allow capturing variables from the enclosing scope either
				3671	explicitly by name, or implicitly using a default capture. Explicit captures
				3672	require each variable to be listed, as
				3673	either a value or reference capture:</p>
				3674
				3675	<pre>int weight = 3;
				3676	int sum = 0;
				3677	// Captures `weight` by value and `sum` by reference.
				3678	std::for_each(v.begin(), v.end(), [weight, &sum](int x) {
				3679	sum += weight * x;
				3680	});
				3681	</pre>
				3682
				3683
				3684	Default captures implicitly capture any variable referenced in the
				3685	lambda body, including <code>this</code> if any members are used:
				3686
				3687	<pre>const std::vector<int> lookup_table = ...;
				3688	std::vector<int> indices = ...;
				3689	// Captures `lookup_table` by reference, sorts `indices` by the value
				3690	// of the associated element in `lookup_table`.
				3691	std::sort(indices.begin(), indices.end(), [&](int a, int b) {
				3692	return lookup_table[a] < lookup_table[b];
				3693	});
				3694	</pre>
				3695
				3696	<p>Lambdas were introduced in C++11 along with a set of utilities
				3697	for working with function objects, such as the polymorphic
				3698	wrapper <code>std::function</code>.
				3699	</p>
				3700	</div>
				3701
				3702	<div class="pros">
				3703	<ul>
				3704	<li>Lambdas are much more concise than other ways of
				3705	defining function objects to be passed to STL
				3706	algorithms, which can be a readability
				3707	improvement.</li>
				3708
				3709	<li>Appropriate use of default captures can remove
				3710	redundancy and highlight important exceptions from
				3711	the default.</li>
				3712
				3713	<li>Lambdas, <code>std::function</code>, and
				3714	<code>std::bind</code> can be used in combination as a
				3715	general purpose callback mechanism; they make it easy
				3716	to write functions that take bound functions as
				3717	arguments.</li>
				3718	</ul>
				3719	</div>
				3720
				3721	<div class="cons">
				3722	<ul>
				3723	<li>Variable capture in lambdas can be a source of dangling-pointer
				3724	bugs, particularly if a lambda escapes the current scope.</li>
				3725
				3726	<li>Default captures by value can be misleading because they do not prevent
				3727	dangling-pointer bugs. Capturing a pointer by value doesn't cause a deep
				3728	copy, so it often has the same lifetime issues as capture by reference.
				3729	This is especially confusing when capturing 'this' by value, since the use
				3730	of 'this' is often implicit.</li>
				3731
				3732	<li>It's possible for use of lambdas to get out of
				3733	hand; very long nested anonymous functions can make
				3734	code harder to understand.</li>
				3735
				3736	</ul>
				3737	</div>
				3738
				3739	<div class="decision">
				3740	<ul>
				3741	<li>Use lambda expressions where appropriate, with formatting as
				3742	described <a href="#Formatting_Lambda_Expressions">below</a>.</li>
				3743	<li>Prefer explicit captures if the lambda may escape the current scope.
				3744	For example, instead of:
				3745	<pre class="badcode">{
				3746	Foo foo;
				3747	...
				3748	executor->Schedule([&] { Frobnicate(foo); })
				3749	...
				3750	}
				3751	// BAD! The fact that the lambda makes use of a reference to `foo` and
				3752	// possibly `this` (if `Frobnicate` is a member function) may not be
				3753	// apparent on a cursory inspection. If the lambda is invoked after
				3754	// the function returns, that would be bad, because both `foo`
				3755	// and the enclosing object could have been destroyed.
				3756	</pre>
				3757	prefer to write:
				3758	<pre>{
				3759	Foo foo;
				3760	...
				3761	executor->Schedule([&foo] { Frobnicate(foo); })
				3762	...
				3763	}
				3764	// BETTER - The compile will fail if `Frobnicate` is a member
				3765	// function, and it's clearer that `foo` is dangerously captured by
				3766	// reference.
				3767	</pre>
				3768	</li>
				3769	<li>Use default capture by reference ([&]) only when the
				3770	lifetime of the lambda is obviously shorter than any potential
				3771	captures.
				3772	</li>
				3773	<li>Use default capture by value ([=]) only as a means of binding a
				3774	few variables for a short lambda, where the set of captured
				3775	variables is obvious at a glance. Prefer not to write long or
				3776	complex lambdas with default capture by value.
				3777	</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	3778	<li>Specify the return type of the lambda explicitly if that will
				3779	make it more obvious to readers, as with
				3780	<a href="#auto"><code>auto</code></a>.</li>
				3781
				3782	</ul>
				3783	</div>
				3784
				3785	</div>
				3786
				3787	<h3 id="Template_metaprogramming">Template metaprogramming</h3>
				3788	<div class="summary">
				3789	<p>Avoid complicated template programming.</p>
				3790	</div>
				3791
				3792	<div class="stylebody">
				3793
				3794	<div class="definition">
				3795	<p>Template metaprogramming refers to a family of techniques that
				3796	exploit the fact that the C++ template instantiation mechanism is
				3797	Turing complete and can be used to perform arbitrary compile-time
				3798	computation in the type domain.</p>
				3799	</div>
				3800
				3801	<div class="pros">
				3802	<p>Template metaprogramming allows extremely flexible interfaces that
				3803	are type safe and high performance. Facilities like
				3804
				3805	<a href="https://code.google.com/p/googletest/">Google Test</a>,
				3806	<code>std::tuple</code>, <code>std::function</code>, and
				3807	Boost.Spirit would be impossible without it.</p>
				3808	</div>
				3809
				3810	<div class="cons">
				3811	<p>The techniques used in template metaprogramming are often obscure
				3812	to anyone but language experts. Code that uses templates in
				3813	complicated ways is often unreadable, and is hard to debug or
				3814	maintain.</p>
				3815
				3816	<p>Template metaprogramming often leads to extremely poor compiler
				3817	time error messages: even if an interface is simple, the complicated
				3818	implementation details become visible when the user does something
				3819	wrong.</p>
				3820
				3821	<p>Template metaprogramming interferes with large scale refactoring by
				3822	making the job of refactoring tools harder. First, the template code
				3823	is expanded in multiple contexts, and it's hard to verify that the
				3824	transformation makes sense in all of them. Second, some refactoring
				3825	tools work with an AST that only represents the structure of the code
				3826	after template expansion. It can be difficult to automatically work
				3827	back to the original source construct that needs to be
				3828	rewritten.</p>
				3829	</div>
				3830
				3831	<div class="decision">
				3832	<p>Template metaprogramming sometimes allows cleaner and easier-to-use
				3833	interfaces than would be possible without it, but it's also often a
				3834	temptation to be overly clever. It's best used in a small number of
				3835	low level components where the extra maintenance burden is spread out
				3836	over a large number of uses.</p>
				3837
				3838	<p>Think twice before using template metaprogramming or other
				3839	complicated template techniques; think about whether the average
				3840	member of your team will be able to understand your code well enough
				3841	to maintain it after you switch to another project, or whether a
				3842	non-C++ programmer or someone casually browsing the code base will be
				3843	able to understand the error messages or trace the flow of a function
				3844	they want to call. If you're using recursive template instantiations
				3845	or type lists or metafunctions or expression templates, or relying on
				3846	SFINAE or on the <code>sizeof</code> trick for detecting function
				3847	overload resolution, then there's a good chance you've gone too
				3848	far.</p>
				3849
				3850	<p>If you use template metaprogramming, you should expect to put
				3851	considerable effort into minimizing and isolating the complexity. You
				3852	should hide metaprogramming as an implementation detail whenever
				3853	possible, so that user-facing headers are readable, and you should
				3854	make sure that tricky code is especially well commented. You should
				3855	carefully document how the code is used, and you should say something
				3856	about what the "generated" code looks like. Pay extra attention to the
				3857	error messages that the compiler emits when users make mistakes. The
				3858	error messages are part of your user interface, and your code should
				3859	be tweaked as necessary so that the error messages are understandable
				3860	and actionable from a user point of view.</p>
				3861
				3862	</div>
				3863	</div>
				3864
				3865
				3866	<h3 id="Boost">Boost</h3>
				3867
				3868	<div class="summary">
				3869	<p>Use only approved libraries from the Boost library
				3870	collection.</p>
				3871	</div>
				3872
				3873	<div class="stylebody">
				3874
				3875	<div class="definition">
				3876	<p> The
				3877	<a href="https://www.boost.org/">
				3878	Boost library collection</a> is a popular collection of
				3879	peer-reviewed, free, open-source C++ libraries.</p>
				3880	</div>
				3881
				3882	<div class="pros">
				3883	<p>Boost code is generally very high-quality, is widely
				3884	portable, and fills many important gaps in the C++
				3885	standard library, such as type traits and better binders.</p>
				3886	</div>
				3887
				3888	<div class="cons">
				3889	<p>Some Boost libraries encourage coding practices which can
				3890	hamper readability, such as metaprogramming and other
				3891	advanced template techniques, and an excessively
				3892	"functional" style of programming. </p>
				3893	</div>
				3894
				3895	<div class="decision">
				3896
				3897
				3898
				3899	<div>
				3900	<p>In order to maintain a high level of readability for
				3901	all contributors who might read and maintain code, we
				3902	only allow an approved subset of Boost features.
				3903	Currently, the following libraries are permitted:</p>
				3904
				3905	<ul>
				3906	<li>
				3907	<a href="https://www.boost.org/libs/utility/call_traits.htm">
				3908	Call Traits</a> from <code>boost/call_traits.hpp</code></li>
				3909
				3910	<li><a href="https://www.boost.org/libs/utility/compressed_pair.htm">
				3911	Compressed Pair</a> from <code>boost/compressed_pair.hpp</code></li>
				3912
				3913	<li><a href="https://www.boost.org/libs/graph/">
				3914	The Boost Graph Library (BGL)</a> from <code>boost/graph</code>,
				3915	except serialization (<code>adj_list_serialize.hpp</code>) and
				3916	parallel/distributed algorithms and data structures
				3917	(<code>boost/graph/parallel/*</code> and
				3918	<code>boost/graph/distributed/*</code>).</li>
				3919
				3920	<li><a href="https://www.boost.org/libs/property_map/">
				3921	Property Map</a> from <code>boost/property_map</code>, except
				3922	parallel/distributed property maps (<code>boost/property_map/parallel/*</code>).</li>
				3923
				3924	<li><a href="https://www.boost.org/libs/iterator/">
				3925	Iterator</a> from <code>boost/iterator</code></li>
				3926
				3927	<li>The part of <a href="https://www.boost.org/libs/polygon/">
				3928	Polygon</a> that deals with Voronoi diagram
				3929	construction and doesn't depend on the rest of
				3930	Polygon:
				3931	<code>boost/polygon/voronoi_builder.hpp</code>,
				3932	<code>boost/polygon/voronoi_diagram.hpp</code>, and
				3933	<code>boost/polygon/voronoi_geometry_type.hpp</code></li>
				3934
				3935	<li><a href="https://www.boost.org/libs/bimap/">
				3936	Bimap</a> from <code>boost/bimap</code></li>
				3937
				3938	<li><a href="https://www.boost.org/libs/math/doc/html/dist.html">
				3939	Statistical Distributions and Functions</a> from
				3940	<code>boost/math/distributions</code></li>
				3941
				3942	<li><a href="https://www.boost.org/libs/math/doc/html/special.html">
				3943	Special Functions</a> from <code>boost/math/special_functions</code></li>
				3944
				3945	<li><a href="https://www.boost.org/libs/multi_index/">
				3946	Multi-index</a> from <code>boost/multi_index</code></li>
				3947
				3948	<li><a href="https://www.boost.org/libs/heap/">
				3949	Heap</a> from <code>boost/heap</code></li>
				3950
				3951	<li>The flat containers from
				3952	<a href="https://www.boost.org/libs/container/">Container</a>:
				3953	<code>boost/container/flat_map</code>, and
				3954	<code>boost/container/flat_set</code></li>
				3955
				3956	<li><a href="https://www.boost.org/libs/intrusive/">Intrusive</a>
				3957	from <code>boost/intrusive</code>.</li>
				3958
				3959	<li><a href="https://www.boost.org/libs/sort/">The
				3960	<code>boost/sort</code> library</a>.</li>
				3961
				3962	<li><a href="https://www.boost.org/libs/preprocessor/">Preprocessor</a>
				3963	from <code>boost/preprocessor</code>.</li>
				3964	</ul>
				3965
				3966	<p>We are actively considering adding other Boost
				3967	features to the list, so this list may be expanded in
				3968	the future.</p>
				3969	</div>
				3970
				3971	<p>The following libraries are permitted, but their use
				3972	is discouraged because they've been superseded by
				3973	standard libraries in C++11:</p>
				3974
				3975	<ul>
				3976	<li><a href="https://www.boost.org/libs/array/">
				3977	Array</a> from <code>boost/array.hpp</code>: use
				3978	<a href="http://en.cppreference.com/w/cpp/container/array">
				3979	<code>std::array</code></a> instead.</li>
				3980
				3981	<li><a href="https://www.boost.org/libs/ptr_container/">
				3982	Pointer Container</a> from <code>boost/ptr_container</code>: use containers of
				3983	<a href="http://en.cppreference.com/w/cpp/memory/unique_ptr">
				3984	<code>std::unique_ptr</code></a> instead.</li>
				3985	</ul>
				3986	</div>
				3987
				3988	</div>
				3989
				3990
				3991
				3992	<h3 id="std_hash">std::hash</h3>
				3993
				3994	<div class="summary">
				3995	<p>Do not define specializations of <code>std::hash</code>.</p>
				3996	</div>
				3997
				3998	<div class="stylebody">
				3999
				4000	<div class="definition">
				4001	<p><code>std::hash<T></code> is the function object that the
				4002	C++11 hash containers use to hash keys of type <code>T</code>,
				4003	unless the user explicitly specifies a different hash function. For
				4004	example, <code>std::unordered_map<int, string></code> is a hash
				4005	map that uses <code>std::hash<int></code> to hash its keys,
				4006	whereas <code>std::unordered_map<int, string, MyIntHash></code>
				4007	uses <code>MyIntHash</code>.</p>
				4008
				4009	<p><code>std::hash</code> is defined for all integral, floating-point,
				4010	pointer, and <code>enum</code> types, as well as some standard library
				4011	types such as <code>string</code> and <code>unique_ptr</code>. Users
				4012	can enable it to work for their own types by defining specializations
				4013	of it for those types.</p>
				4014	</div>
				4015
				4016	<div class="pros">
				4017	<p><code>std::hash</code> is easy to use, and simplifies the code
				4018	since you don't have to name it explicitly. Specializing
				4019	<code>std::hash</code> is the standard way of specifying how to
				4020	hash a type, so it's what outside resources will teach, and what
				4021	new engineers will expect.</p>
				4022	</div>
				4023
				4024	<div class="cons">
				4025	<p><code>std::hash</code> is hard to specialize. It requires a lot
				4026	of boilerplate code, and more importantly, it combines responsibility
				4027	for identifying the hash inputs with responsibility for executing the
				4028	hashing algorithm itself. The type author has to be responsible for
				4029	the former, but the latter requires expertise that a type author
				4030	usually doesn't have, and shouldn't need. The stakes here are high
				4031	because low-quality hash functions can be security vulnerabilities,
				4032	due to the emergence of
				4033	<a href="https://emboss.github.io/blog/2012/12/14/breaking-murmur-hash-flooding-dos-reloaded/">
				4034	hash flooding attacks</a>.</p>
				4035
				4036	<p>Even for experts, <code>std::hash</code> specializations are
				4037	inordinately difficult to implement correctly for compound types,
				4038	because the implementation cannot recursively call <code>std::hash</code>
				4039	on data members. High-quality hash algorithms maintain large
				4040	amounts of internal state, and reducing that state to the
				4041	<code>size_t</code> bytes that <code>std::hash</code>
				4042	returns is usually the slowest part of the computation, so it
				4043	should not be done more than once.</p>
				4044
				4045	<p>Due to exactly that issue, <code>std::hash</code> does not work
				4046	with <code>std::pair</code> or <code>std::tuple</code>, and the
				4047	language does not allow us to extend it to support them.</p>
				4048	</div>
				4049
				4050	<div class="decision">
				4051	<p>You can use <code>std::hash</code> with the types that it supports
				4052	"out of the box", but do not specialize it to support additional types.
				4053	If you need a hash table with a key type that <code>std::hash</code>
				4054	does not support, consider using legacy hash containers (e.g.
				4055	<code>hash_map</code>) for now; they use a different default hasher,
				4056	which is unaffected by this prohibition.</p>
				4057
				4058	<p>If you want to use the standard hash containers anyway, you will
				4059	need to specify a custom hasher for the key type, e.g.</p>
				4060	<pre>std::unordered_map<MyKeyType, Value, MyKeyTypeHasher> my_map;
				4061	</pre><p>
				4062	Consult with the type's owners to see if there is an existing hasher
				4063	that you can use; otherwise work with them to provide one,
				4064	or roll your own.</p>
				4065
				4066	<p>We are planning to provide a hash function that can work with any type,
				4067	using a new customization mechanism that doesn't have the drawbacks of
				4068	<code>std::hash</code>.</p>
				4069	</div>
				4070
				4071	</div>
				4072
				4073	<h3 id="C++11">C++11</h3>
				4074
				4075	<div class="summary">
				4076	<p>Use libraries and language extensions from C++11 when appropriate.
				4077	Consider portability to other environments
				4078	before using C++11 features in your
				4079	project. </p>
				4080
				4081	</div>
				4082
				4083	<div class="stylebody">
				4084
				4085	<div class="definition">
				4086	<p> C++11 contains <a href="https://en.wikipedia.org/wiki/C%2B%2B11">
				4087	significant changes</a> both to the language and
				4088	libraries. </p>
				4089	</div>
				4090
				4091	<div class="pros">
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	4092	<p>C++11 was the official standard until 2014, and
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4093	is supported by most C++ compilers. It standardizes
				4094	some common C++ extensions that we use already, allows
				4095	shorthands for some operations, and has some performance
				4096	and safety improvements.</p>
				4097	</div>
				4098
				4099	<div class="cons">
				4100	<p>The C++11 standard is substantially more complex than
				4101	its predecessor (1,300 pages versus 800 pages), and is
				4102	unfamiliar to many developers. The long-term effects of
				4103	some features on code readability and maintenance are
				4104	unknown. We cannot predict when its various features will
				4105	be implemented uniformly by tools that may be of
				4106	interest, particularly in the case of projects that are
				4107	forced to use older versions of tools.</p>
				4108
				4109	<p>As with <a href="#Boost">Boost</a>, some C++11
				4110	extensions encourage coding practices that hamper
				4111	readability—for example by removing
				4112	checked redundancy (such as type names) that may be
				4113	helpful to readers, or by encouraging template
				4114	metaprogramming. Other extensions duplicate functionality
				4115	available through existing mechanisms, which may lead to confusion
				4116	and conversion costs.</p>
				4117
				4118
				4119	</div>
				4120
				4121	<div class="decision">
				4122
				4123	<p>C++11 features may be used unless specified otherwise.
				4124	In addition to what's described in the rest of the style
				4125	guide, the following C++11 features may not be used:</p>
				4126
				4127	<ul>
				4128
				4129
				4130
				4131
				4132
				4133
				4134
				4135
				4136	<li>Compile-time rational numbers
				4137	(<code><ratio></code>), because of concerns that
				4138	it's tied to a more template-heavy interface
				4139	style.</li>
				4140
				4141	<li>The <code><cfenv></code> and
				4142	<code><fenv.h></code> headers, because many
				4143	compilers do not support those features reliably.</li>
				4144
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4145
				4146
				4147
				4148	</ul>
				4149	</div>
				4150
				4151	</div>
				4152
				4153	<h3 id="Nonstandard_Extensions">Nonstandard Extensions</h3>
				4154
				4155	<div class="summary">
				4156	<p>Nonstandard extensions to C++ may not be used unless otherwise specified.</p>
				4157	</div>
				4158	<div class="stylebody">
				4159	<div class="definition">
				4160	<p>Compilers support various extensions that are not part of standard C++. Such
				4161	extensions include GCC's <code>__attribute__</code>, intrinsic functions such
				4162	as <code>__builtin_prefetch</code>, designated initializers (e.g.
				4163	<code>Foo f = {.field = 3}</code>), inline assembly, <code>__COUNTER__</code>,
				4164	<code>__PRETTY_FUNCTION__</code>, compound statement expressions (e.g.
				4165	<code>foo = ({ int x; Bar(&x); x })</code>, variable-length arrays and
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4166	<code>alloca()</code>, and the "<a href="https://en.wikipedia.org/wiki/Elvis_operator">Elvis Operator</a>"
				4167	<code>a?:b</code>.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4168	</div>
				4169
				4170	<div class="pros">
				4171	<ul>
				4172	<li>Nonstandard extensions may provide useful features that do not exist
				4173	in standard C++. For example, some people think that designated
				4174	initializers are more readable than standard C++ features like
				4175	constructors.</li>
				4176	<li>Important performance guidance to the compiler can only be specified
				4177	using extensions.</li>
				4178	</ul>
				4179	</div>
				4180
				4181	<div class="cons">
				4182	<ul>
				4183	<li>Nonstandard extensions do not work in all compilers. Use of nonstandard
				4184	extensions reduces portability of code.</li>
				4185	<li>Even if they are supported in all targeted compilers, the extensions
				4186	are often not well-specified, and there may be subtle behavior differences
				4187	between compilers.</li>
				4188	<li>Nonstandard extensions add to the language features that a reader must
				4189	know to understand the code.</li>
				4190	</ul>
				4191	</div>
				4192
				4193	<div class="decision">
				4194	<p>Do not use nonstandard extensions. You may use portability wrappers that
				4195	are implemented using nonstandard extensions, so long as those wrappers
				4196
				4197	are provided by a designated project-wide
				4198	portability header.</p>
				4199	</div>
				4200	</div>
				4201
				4202	<h3 id="Aliases">Aliases</h3>
				4203
				4204	<div class="summary">
				4205	<p>Public aliases are for the benefit of an API's user, and should be clearly documented.</p>
				4206	</div>
				4207	<div class="stylebody">
				4208	<div class="definition">
				4209	<p>There are several ways to create names that are aliases of other entities:</p>
				4210	<pre>typedef Foo Bar;
				4211	using Bar = Foo;
				4212	using other_namespace::Foo;
				4213	</pre>
				4214
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4215	<p>In new code, <code>using</code> is preferable to <code>typedef</code>,
				4216	because it provides a more consistent syntax with the rest of C++ and works
				4217	with templates.</p>
				4218
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4219	<p>Like other declarations, aliases declared in a header file are part of that
				4220	header's public API unless they're in a function definition, in the private portion of a class,
				4221	or in an explicitly-marked internal namespace. Aliases in such areas or in .cc files are
				4222	implementation details (because client code can't refer to them), and are not restricted by this
				4223	rule.</p>
				4224	</div>
				4225
				4226	<div class="pros">
				4227	<ul>
				4228	<li>Aliases can improve readability by simplifying a long or complicated name.</li>
				4229	<li>Aliases can reduce duplication by naming in one place a type used repeatedly in an API,
				4230	which <em>might</em> make it easier to change the type later.
				4231	</li>
				4232	</ul>
				4233	</div>
				4234
				4235	<div class="cons">
				4236	<ul>
				4237	<li>When placed in a header where client code can refer to them, aliases increase the
				4238	number of entities in that header's API, increasing its complexity.</li>
				4239	<li>Clients can easily rely on unintended details of public aliases, making
				4240	changes difficult.</li>
				4241	<li>It can be tempting to create a public alias that is only intended for use
				4242	in the implementation, without considering its impact on the API, or on maintainability.</li>
				4243	<li>Aliases can create risk of name collisions</li>
				4244	<li>Aliases can reduce readability by giving a familiar construct an unfamiliar name</li>
				4245	<li>Type aliases can create an unclear API contract:
				4246	it is unclear whether the alias is guaranteed to be identical to the type it aliases,
				4247	to have the same API, or only to be usable in specified narrow ways</li>
				4248	</ul>
				4249	</div>
				4250
				4251	<div class="decision">
				4252	<p>Don't put an alias in your public API just to save typing in the implementation;
				4253	do so only if you intend it to be used by your clients.</p>
				4254	<p>When defining a public alias, document the intent of
				4255	the new name, including whether it is guaranteed to always be the same as the type
				4256	it's currently aliased to, or whether a more limited compatibility is
				4257	intended. This lets the user know whether they can treat the types as
				4258	substitutable or whether more specific rules must be followed, and can help the
				4259	implementation retain some degree of freedom to change the alias.</p>
				4260	<p>Don't put namespace aliases in your public API. (See also <a href="#Namespaces">Namespaces</a>).
				4261	</p>
				4262
				4263	<p>For example, these aliases document how they are intended to be used in client code:</p>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4264	<pre>namespace mynamespace {
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4265	// Used to store field measurements. DataPoint may change from Bar* to some internal type.
				4266	// Client code should treat it as an opaque pointer.
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4267	using DataPoint = foo::Bar*;
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4268
				4269	// A set of measurements. Just an alias for user convenience.
				4270	using TimeSeries = std::unordered_set<DataPoint, std::hash<DataPoint>, DataPointComparator>;
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4271	} // namespace mynamespace
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4272	</pre>
				4273
				4274	<p>These aliases don't document intended use, and half of them aren't meant for client use:</p>
				4275
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4276	<pre class="badcode">namespace mynamespace {
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4277	// Bad: none of these say how they should be used.
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4278	using DataPoint = foo::Bar*;
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4279	using std::unordered_set; // Bad: just for local convenience
				4280	using std::hash; // Bad: just for local convenience
				4281	typedef unordered_set<DataPoint, hash<DataPoint>, DataPointComparator> TimeSeries;
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4282	} // namespace mynamespace
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4283	</pre>
				4284
				4285	<p>However, local convenience aliases are fine in function definitions, private sections of
				4286	classes, explicitly marked internal namespaces, and in .cc files:</p>
				4287
				4288	<pre>// In a .cc file
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4289	using foo::Bar;
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4290	</pre>
				4291
				4292	</div>
				4293	</div>
				4294
				4295	<h2 id="Naming">Naming</h2>
				4296
				4297	<p>The most important consistency rules are those that govern
				4298	naming. The style of a name immediately informs us what sort of
				4299	thing the named entity is: a type, a variable, a function, a
				4300	constant, a macro, etc., without requiring us to search for the
				4301	declaration of that entity. The pattern-matching engine in our
				4302	brains relies a great deal on these naming rules.
				4303	</p>
				4304
				4305	<p>Naming rules are pretty arbitrary, but
				4306	we feel that
				4307	consistency is more important than individual preferences in this
				4308	area, so regardless of whether you find them sensible or not,
				4309	the rules are the rules.</p>
				4310
				4311	<h3 id="General_Naming_Rules">General Naming Rules</h3>
				4312
				4313	<div class="summary">
				4314	<p>Names should be descriptive; avoid abbreviation.</p>
				4315	</div>
				4316
				4317	<div class="stylebody">
				4318	<p>Give as descriptive a name as possible, within reason.
				4319	Do not worry about saving horizontal space as it is far
				4320	more important to make your code immediately
				4321	understandable by a new reader. Do not use abbreviations
				4322	that are ambiguous or unfamiliar to readers outside your
				4323	project, and do not abbreviate by deleting letters within
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4324	a word. Abbreviations that would be familiar to someone
				4325	outside your project with relevant domain knowledge are OK.
				4326	As a rule of thumb, an abbreviation is probably OK if it's listed
				4327	in
				4328
				4329	Wikipedia.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4330
				4331	<pre>int price_count_reader; // No abbreviation.
				4332	int num_errors; // "num" is a widespread convention.
				4333	int num_dns_connections; // Most people know what "DNS" stands for.
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4334	int lstm_size; // "LSTM" is a common machine learning abbreviation.
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4335	</pre>
				4336
				4337	<pre class="badcode">int n; // Meaningless.
				4338	int nerr; // Ambiguous abbreviation.
				4339	int n_comp_conns; // Ambiguous abbreviation.
				4340	int wgc_connections; // Only your group knows what this stands for.
				4341	int pc_reader; // Lots of things can be abbreviated "pc".
				4342	int cstmr_id; // Deletes internal letters.
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4343	FooBarRequestInfo fbri; // Not even a word.
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4344	</pre>
				4345
				4346	<p>Note that certain universally-known abbreviations are OK, such as
				4347	<code>i</code> for an iteration variable and <code>T</code> for a
				4348	template parameter.</p>
				4349
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4350	<p>For some symbols, this style guide recommends names to start with a capital
				4351	letter and to have a capital letter for each new word (a.k.a.
				4352	"<a href="https://en.wikipedia.org/wiki/Camel_case">Camel Case</a>"
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	4353	or "Pascal case"). When abbreviations or acronyms appear in such
				4354	names, prefer to capitalize the abbreviations or acronyms as single words (i.e
				4355	<code>StartRpc()</code>, not <code>StartRPC()</code>).</p>
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4356
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4357	<p>Template parameters should follow the naming style for their
				4358	category: type template parameters should follow the rules for
				4359	<a href="#Type_Names">type names</a>, and non-type template
				4360	parameters should follow the rules for <a href="#Variable_Names">
				4361	variable names</a>.
				4362
				4363	</p></div>
				4364
				4365	<h3 id="File_Names">File Names</h3>
				4366
				4367	<div class="summary">
				4368	<p>Filenames should be all lowercase and can include
				4369	underscores (<code>_</code>) or dashes (<code>-</code>).
				4370	Follow the convention that your
				4371
				4372	project uses. If there is no consistent
				4373	local pattern to follow, prefer "_".</p>
				4374	</div>
				4375
				4376	<div class="stylebody">
				4377
				4378	<p>Examples of acceptable file names:</p>
				4379
				4380	<ul>
				4381	<li><code>my_useful_class.cc</code></li>
				4382	<li><code>my-useful-class.cc</code></li>
				4383	<li><code>myusefulclass.cc</code></li>
				4384	<li><code>myusefulclass_test.cc // _unittest and _regtest are deprecated.</code></li>
				4385	</ul>
				4386
				4387	<p>C++ files should end in <code>.cc</code> and header files should end in
				4388	<code>.h</code>. Files that rely on being textually included at specific points
				4389	should end in <code>.inc</code> (see also the section on
				4390	<a href="#Self_contained_Headers">self-contained headers</a>).</p>
				4391
				4392	<p>Do not use filenames that already exist in
				4393	<code>/usr/include</code>, such as <code>db.h</code>.</p>
				4394
				4395	<p>In general, make your filenames very specific. For
				4396	example, use <code>http_server_logs.h</code> rather than
				4397	<code>logs.h</code>. A very common case is to have a pair
				4398	of files called, e.g., <code>foo_bar.h</code> and
				4399	<code>foo_bar.cc</code>, defining a class called
				4400	<code>FooBar</code>.</p>
				4401
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4402	</div>
				4403
				4404	<h3 id="Type_Names">Type Names</h3>
				4405
				4406	<div class="summary">
				4407	<p>Type names start with a capital letter and have a capital
				4408	letter for each new word, with no underscores:
				4409	<code>MyExcitingClass</code>, <code>MyExcitingEnum</code>.</p>
				4410	</div>
				4411
				4412	<div class="stylebody">
				4413
				4414	<p>The names of all types — classes, structs, type aliases,
				4415	enums, and type template parameters — have the same naming convention.
				4416	Type names should start with a capital letter and have a capital letter
				4417	for each new word. No underscores. For example:</p>
				4418
				4419	<pre>// classes and structs
				4420	class UrlTable { ...
				4421	class UrlTableTester { ...
				4422	struct UrlTableProperties { ...
				4423
				4424	// typedefs
				4425	typedef hash_map<UrlTableProperties *, string> PropertiesMap;
				4426
				4427	// using aliases
				4428	using PropertiesMap = hash_map<UrlTableProperties *, string>;
				4429
				4430	// enums
				4431	enum UrlTableErrors { ...
				4432	</pre>
				4433
				4434	</div>
				4435
				4436	<h3 id="Variable_Names">Variable Names</h3>
				4437
				4438	<div class="summary">
				4439	<p>The names of variables (including function parameters) and data members are
				4440	all lowercase, with underscores between words. Data members of classes (but not
				4441	structs) additionally have trailing underscores. For instance:
				4442	<code>a_local_variable</code>, <code>a_struct_data_member</code>,
				4443	<code>a_class_data_member_</code>.</p>
				4444	</div>
				4445
				4446	<div class="stylebody">
				4447
				4448	<h4 class="stylepoint_subsection">Common Variable names</h4>
				4449
				4450	<p>For example:</p>
				4451
				4452	<pre>string table_name; // OK - uses underscore.
				4453	string tablename; // OK - all lowercase.
				4454	</pre>
				4455
				4456	<pre class="badcode">string tableName; // Bad - mixed case.
				4457	</pre>
				4458
				4459	<h4 class="stylepoint_subsection">Class Data Members</h4>
				4460
				4461	<p>Data members of classes, both static and non-static, are
				4462	named like ordinary nonmember variables, but with a
				4463	trailing underscore.</p>
				4464
				4465	<pre>class TableInfo {
				4466	...
				4467	private:
				4468	string table_name_; // OK - underscore at end.
				4469	string tablename_; // OK.
				4470	static Pool<TableInfo>* pool_; // OK.
				4471	};
				4472	</pre>
				4473
				4474	<h4 class="stylepoint_subsection">Struct Data Members</h4>
				4475
				4476	<p>Data members of structs, both static and non-static,
				4477	are named like ordinary nonmember variables. They do not have
				4478	the trailing underscores that data members in classes have.</p>
				4479
				4480	<pre>struct UrlTableProperties {
				4481	string name;
				4482	int num_entries;
				4483	static Pool<UrlTableProperties>* pool;
				4484	};
				4485	</pre>
				4486
				4487
				4488	<p>See <a href="#Structs_vs._Classes">Structs vs.
				4489	Classes</a> for a discussion of when to use a struct
				4490	versus a class.</p>
				4491
				4492	</div>
				4493
				4494	<h3 id="Constant_Names">Constant Names</h3>
				4495
				4496	<div class="summary">
				4497	<p>Variables declared constexpr or const, and whose value is fixed for
				4498	the duration of the program, are named with a leading "k" followed
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	4499	by mixed case. Underscores can be used as separators in the rare cases
				4500	where capitalization cannot be used for separation. For example:</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4501	</div>
				4502
				4503	<pre>const int kDaysInAWeek = 7;
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	4504	const int kAndroid8_0_0 = 24; // Android 8.0.0
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4505	</pre>
				4506
				4507	<div class="stylebody">
				4508
				4509	<p>All such variables with static storage duration (i.e. statics and globals,
				4510	see <a href="http://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration">
				4511	Storage Duration</a> for details) should be named this way. This
				4512	convention is optional for variables of other storage classes, e.g. automatic
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4513	variables, otherwise the usual variable naming rules apply.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4514
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4515	</div>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4516
				4517	<h3 id="Function_Names">Function Names</h3>
				4518
				4519	<div class="summary">
				4520	<p>Regular functions have mixed case; accessors and mutators may be named
				4521	like variables.</p>
				4522	</div>
				4523
				4524	<div class="stylebody">
				4525
				4526	<p>Ordinarily, functions should start with a capital letter and have a
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4527	capital letter for each new word.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4528
				4529	<pre>AddTableEntry()
				4530	DeleteUrl()
				4531	OpenFileOrDie()
				4532	</pre>
				4533
				4534	<p>(The same naming rule applies to class- and namespace-scope
				4535	constants that are exposed as part of an API and that are intended to look
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4536	like functions, because the fact that they're objects rather than functions
				4537	is an unimportant implementation detail.)</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4538
				4539	<p>Accessors and mutators (get and set functions) may be named like
				4540	variables. These often correspond to actual member variables, but this is
				4541	not required. For example, <code>int count()</code> and <code>void
				4542	set_count(int count)</code>.</p>
				4543
				4544	</div>
				4545
				4546	<h3 id="Namespace_Names">Namespace Names</h3>
				4547
				4548	<div class="summary">
				4549	Namespace names are all lower-case. Top-level namespace names are
				4550	based on the project name
				4551	. Avoid collisions
				4552	between nested namespaces and well-known top-level namespaces.
				4553	</div>
				4554
				4555	<div class="stylebody">
				4556	<p>The name of a top-level namespace should usually be the
				4557	name of the project or team whose code is contained in that
				4558	namespace. The code in that namespace should usually be in
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4559	a directory whose basename matches the namespace name (or in
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4560	subdirectories thereof).</p>
				4561
				4562
				4563
				4564
				4565
				4566	<p>Keep in mind that the <a href="#General_Naming_Rules">rule
				4567	against abbreviated names</a> applies to namespaces just as much
				4568	as variable names. Code inside the namespace seldom needs to
				4569	mention the namespace name, so there's usually no particular need
				4570	for abbreviation anyway.</p>
				4571
				4572	<p>Avoid nested namespaces that match well-known top-level
				4573	namespaces. Collisions between namespace names can lead to surprising
				4574	build breaks because of name lookup rules. In particular, do not
				4575	create any nested <code>std</code> namespaces. Prefer unique project
				4576	identifiers
				4577	(<code>websearch::index</code>, <code>websearch::index_util</code>)
				4578	over collision-prone names like <code>websearch::util</code>.</p>
				4579
				4580	<p>For <code>internal</code> namespaces, be wary of other code being
				4581	added to the same <code>internal</code> namespace causing a collision
				4582	(internal helpers within a team tend to be related and may lead to
				4583	collisions). In such a situation, using the filename to make a unique
				4584	internal name is helpful
				4585	(<code>websearch::index::frobber_internal</code> for use
				4586	in <code>frobber.h</code>)</p>
				4587
				4588	</div>
				4589
				4590	<h3 id="Enumerator_Names">Enumerator Names</h3>
				4591
				4592	<div class="summary">
				4593	<p>Enumerators (for both scoped and unscoped enums) should be named <i>either</i> like
				4594	<a href="#Constant_Names">constants</a> or like
				4595	<a href="#Macro_Names">macros</a>: either <code>kEnumName</code> or
				4596	<code>ENUM_NAME</code>.</p>
				4597	</div>
				4598
				4599	<div class="stylebody">
				4600
				4601	<p>Preferably, the individual enumerators should be named
				4602	like <a href="#Constant_Names">constants</a>. However, it
				4603	is also acceptable to name them like
				4604	<a href="#Macro_Names">macros</a>. The enumeration name,
				4605	<code>UrlTableErrors</code> (and
				4606	<code>AlternateUrlTableErrors</code>), is a type, and
				4607	therefore mixed case.</p>
				4608
				4609	<pre>enum UrlTableErrors {
				4610	kOK = 0,
				4611	kErrorOutOfMemory,
				4612	kErrorMalformedInput,
				4613	};
				4614	enum AlternateUrlTableErrors {
				4615	OK = 0,
				4616	OUT_OF_MEMORY = 1,
				4617	MALFORMED_INPUT = 2,
				4618	};
				4619	</pre>
				4620
				4621	<p>Until January 2009, the style was to name enum values
				4622	like <a href="#Macro_Names">macros</a>. This caused
				4623	problems with name collisions between enum values and
				4624	macros. Hence, the change to prefer constant-style naming
				4625	was put in place. New code should prefer constant-style
				4626	naming if possible. However, there is no reason to change
				4627	old code to use constant-style names, unless the old
				4628	names are actually causing a compile-time problem.</p>
				4629
				4630
				4631
				4632	</div>
				4633
				4634	<h3 id="Macro_Names">Macro Names</h3>
				4635
				4636	<div class="summary">
				4637	<p>You're not really going to <a href="#Preprocessor_Macros">
				4638	define a macro</a>, are you? If you do, they're like this:
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4639	<code>MY_MACRO_THAT_SCARES_SMALL_CHILDREN_AND_ADULTS_ALIKE</code>.
				4640	</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4641	</div>
				4642
				4643	<div class="stylebody">
				4644
				4645	<p>Please see the <a href="#Preprocessor_Macros">description
				4646	of macros</a>; in general macros should <em>not</em> be used.
				4647	However, if they are absolutely needed, then they should be
				4648	named with all capitals and underscores.</p>
				4649
				4650	<pre>#define ROUND(x) ...
				4651	#define PI_ROUNDED 3.0
				4652	</pre>
				4653
				4654	</div>
				4655
				4656	<h3 id="Exceptions_to_Naming_Rules">Exceptions to Naming Rules</h3>
				4657
				4658	<div class="summary">
				4659	<p>If you are naming something that is analogous to an
				4660	existing C or C++ entity then you can follow the existing
				4661	naming convention scheme.</p>
				4662	</div>
				4663
				4664	<div class="stylebody">
				4665
				4666	<dl>
				4667	<dt><code>bigopen()</code></dt>
				4668	<dd>function name, follows form of <code>open()</code></dd>
				4669
				4670	<dt><code>uint</code></dt>
				4671	<dd><code>typedef</code></dd>
				4672
				4673	<dt><code>bigpos</code></dt>
				4674	<dd><code>struct</code> or <code>class</code>, follows
				4675	form of <code>pos</code></dd>
				4676
				4677	<dt><code>sparse_hash_map</code></dt>
				4678	<dd>STL-like entity; follows STL naming conventions</dd>
				4679
				4680	<dt><code>LONGLONG_MAX</code></dt>
				4681	<dd>a constant, as in <code>INT_MAX</code></dd>
				4682	</dl>
				4683
				4684	</div>
				4685
				4686	<h2 id="Comments">Comments</h2>
				4687
				4688	<p>Though a pain to write, comments are absolutely vital to
				4689	keeping our code readable. The following rules describe what
				4690	you should comment and where. But remember: while comments are
				4691	very important, the best code is self-documenting. Giving
				4692	sensible names to types and variables is much better than using
				4693	obscure names that you must then explain through comments.</p>
				4694
				4695	<p>When writing your comments, write for your audience: the
				4696	next
				4697	contributor who will need to
				4698	understand your code. Be generous — the next
				4699	one may be you!</p>
				4700
				4701	<h3 id="Comment_Style">Comment Style</h3>
				4702
				4703	<div class="summary">
				4704	<p>Use either the <code>//</code> or <code>/* */</code>
				4705	syntax, as long as you are consistent.</p>
				4706	</div>
				4707
				4708	<div class="stylebody">
				4709
				4710	<p>You can use either the <code>//</code> or the <code>/*
				4711	*/</code> syntax; however, <code>//</code> is
				4712	<em>much</em> more common. Be consistent with how you
				4713	comment and what style you use where.</p>
				4714
				4715	</div>
				4716
				4717	<h3 id="File_Comments">File Comments</h3>
				4718
				4719	<div class="summary">
				4720	<p>Start each file with license boilerplate.</p>
				4721
				4722	<p>File comments describe the contents of a file. If a file declares,
				4723	implements, or tests exactly one abstraction that is documented by a comment
				4724	at the point of declaration, file comments are not required. All other files
				4725	must have file comments.</p>
				4726
				4727	</div>
				4728
				4729	<div class="stylebody">
				4730
				4731	<h4 class="stylepoint_subsection">Legal Notice and Author
				4732	Line</h4>
				4733
				4734
				4735
				4736	<p>Every file should contain license
				4737	boilerplate. Choose the appropriate boilerplate for the
				4738	license used by the project (for example, Apache 2.0,
				4739	BSD, LGPL, GPL).</p>
				4740
				4741	<p>If you make significant changes to a file with an
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4742	author line, consider deleting the author line.
				4743	New files should usually not contain copyright notice or
				4744	author line.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4745
				4746	<h4 class="stylepoint_subsection">File Contents</h4>
				4747
				4748	<p>If a <code>.h</code> declares multiple abstractions, the file-level comment
				4749	should broadly describe the contents of the file, and how the abstractions are
				4750	related. A 1 or 2 sentence file-level comment may be sufficient. The detailed
				4751	documentation about individual abstractions belongs with those abstractions,
				4752	not at the file level.</p>
				4753
				4754	<p>Do not duplicate comments in both the <code>.h</code> and the
				4755	<code>.cc</code>. Duplicated comments diverge.</p>
				4756
				4757	</div>
				4758
				4759	<h3 id="Class_Comments">Class Comments</h3>
				4760
				4761	<div class="summary">
				4762	<p>Every non-obvious class declaration should have an accompanying
				4763	comment that describes what it is for and how it should be used.</p>
				4764	</div>
				4765
				4766	<div class="stylebody">
				4767
				4768	<pre>// Iterates over the contents of a GargantuanTable.
				4769	// Example:
				4770	// GargantuanTableIterator* iter = table->NewIterator();
				4771	// for (iter->Seek("foo"); !iter->done(); iter->Next()) {
				4772	// process(iter->key(), iter->value());
				4773	// }
				4774	// delete iter;
				4775	class GargantuanTableIterator {
				4776	...
				4777	};
				4778	</pre>
				4779
				4780	<p>The class comment should provide the reader with enough information to know
				4781	how and when to use the class, as well as any additional considerations
				4782	necessary to correctly use the class. Document the synchronization assumptions
				4783	the class makes, if any. If an instance of the class can be accessed by
				4784	multiple threads, take extra care to document the rules and invariants
				4785	surrounding multithreaded use.</p>
				4786
				4787	<p>The class comment is often a good place for a small example code snippet
				4788	demonstrating a simple and focused usage of the class.</p>
				4789
				4790	<p>When sufficiently separated (e.g. <code>.h</code> and <code>.cc</code>
				4791	files), comments describing the use of the class should go together with its
				4792	interface definition; comments about the class operation and implementation
				4793	should accompany the implementation of the class's methods.</p>
				4794
				4795	</div>
				4796
				4797	<h3 id="Function_Comments">Function Comments</h3>
				4798
				4799	<div class="summary">
				4800	<p>Declaration comments describe use of the function (when it is
				4801	non-obvious); comments at the definition of a function describe
				4802	operation.</p>
				4803	</div>
				4804
				4805	<div class="stylebody">
				4806
				4807	<h4 class="stylepoint_subsection">Function Declarations</h4>
				4808
				4809	<p>Almost every function declaration should have comments immediately
				4810	preceding it that describe what the function does and how to use
				4811	it. These comments may be omitted only if the function is simple and
				4812	obvious (e.g. simple accessors for obvious properties of the
				4813	class). These comments should be descriptive ("Opens the file")
				4814	rather than imperative ("Open the file"); the comment describes the
				4815	function, it does not tell the function what to do. In general, these
				4816	comments do not describe how the function performs its task. Instead,
				4817	that should be left to comments in the function definition.</p>
				4818
				4819	<p>Types of things to mention in comments at the function
				4820	declaration:</p>
				4821
				4822	<ul>
				4823	<li>What the inputs and outputs are.</li>
				4824
				4825	<li>For class member functions: whether the object
				4826	remembers reference arguments beyond the duration of
				4827	the method call, and whether it will free them or
				4828	not.</li>
				4829
				4830	<li>If the function allocates memory that the caller
				4831	must free.</li>
				4832
				4833	<li>Whether any of the arguments can be a null
				4834	pointer.</li>
				4835
				4836	<li>If there are any performance implications of how a
				4837	function is used.</li>
				4838
				4839	<li>If the function is re-entrant. What are its
				4840	synchronization assumptions?</li>
				4841	</ul>
				4842
				4843	<p>Here is an example:</p>
				4844
				4845	<pre>// Returns an iterator for this table. It is the client's
				4846	// responsibility to delete the iterator when it is done with it,
				4847	// and it must not use the iterator once the GargantuanTable object
				4848	// on which the iterator was created has been deleted.
				4849	//
				4850	// The iterator is initially positioned at the beginning of the table.
				4851	//
				4852	// This method is equivalent to:
				4853	// Iterator* iter = table->NewIterator();
				4854	// iter->Seek("");
				4855	// return iter;
				4856	// If you are going to immediately seek to another place in the
				4857	// returned iterator, it will be faster to use NewIterator()
				4858	// and avoid the extra seek.
				4859	Iterator* GetIterator() const;
				4860	</pre>
				4861
				4862	<p>However, do not be unnecessarily verbose or state the
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	4863	completely obvious.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4864
				4865	<p>When documenting function overrides, focus on the
				4866	specifics of the override itself, rather than repeating
				4867	the comment from the overridden function. In many of these
				4868	cases, the override needs no additional documentation and
				4869	thus no comment is required.</p>
				4870
				4871	<p>When commenting constructors and destructors, remember
				4872	that the person reading your code knows what constructors
				4873	and destructors are for, so comments that just say
				4874	something like "destroys this object" are not useful.
				4875	Document what constructors do with their arguments (for
				4876	example, if they take ownership of pointers), and what
				4877	cleanup the destructor does. If this is trivial, just
				4878	skip the comment. It is quite common for destructors not
				4879	to have a header comment.</p>
				4880
				4881	<h4 class="stylepoint_subsection">Function Definitions</h4>
				4882
				4883	<p>If there is anything tricky about how a function does
				4884	its job, the function definition should have an
				4885	explanatory comment. For example, in the definition
				4886	comment you might describe any coding tricks you use,
				4887	give an overview of the steps you go through, or explain
				4888	why you chose to implement the function in the way you
				4889	did rather than using a viable alternative. For instance,
				4890	you might mention why it must acquire a lock for the
				4891	first half of the function but why it is not needed for
				4892	the second half.</p>
				4893
				4894	<p>Note you should <em>not</em> just repeat the comments
				4895	given with the function declaration, in the
				4896	<code>.h</code> file or wherever. It's okay to
				4897	recapitulate briefly what the function does, but the
				4898	focus of the comments should be on how it does it.</p>
				4899
				4900	</div>
				4901
				4902	<h3 id="Variable_Comments">Variable Comments</h3>
				4903
				4904	<div class="summary">
				4905	<p>In general the actual name of the variable should be
				4906	descriptive enough to give a good idea of what the variable
				4907	is used for. In certain cases, more comments are required.</p>
				4908	</div>
				4909
				4910	<div class="stylebody">
				4911
				4912	<h4 class="stylepoint_subsection">Class Data Members</h4>
				4913
				4914	<p>The purpose of each class data member (also called an instance
				4915	variable or member variable) must be clear. If there are any
				4916	invariants (special values, relationships between members, lifetime
				4917	requirements) not clearly expressed by the type and name, they must be
				4918	commented. However, if the type and name suffice (<code>int
				4919	num_events_;</code>), no comment is needed.</p>
				4920
				4921	<p>In particular, add comments to describe the existence and meaning
				4922	of sentinel values, such as nullptr or -1, when they are not
				4923	obvious. For example:</p>
				4924
				4925	<pre>private:
				4926	// Used to bounds-check table accesses. -1 means
				4927	// that we don't yet know how many entries the table has.
				4928	int num_total_entries_;
				4929	</pre>
				4930
				4931	<h4 class="stylepoint_subsection">Global Variables</h4>
				4932
				4933	<p>All global variables should have a comment describing what they
				4934	are, what they are used for, and (if unclear) why it needs to be
				4935	global. For example:</p>
				4936
				4937	<pre>// The total number of tests cases that we run through in this regression test.
				4938	const int kNumTestCases = 6;
				4939	</pre>
				4940
				4941	</div>
				4942
				4943	<h3 id="Implementation_Comments">Implementation Comments</h3>
				4944
				4945	<div class="summary">
				4946	<p>In your implementation you should have comments in tricky,
				4947	non-obvious, interesting, or important parts of your code.</p>
				4948	</div>
				4949
				4950	<div class="stylebody">
				4951
				4952	<h4 class="stylepoint_subsection">Explanatory Comments</h4>
				4953
				4954	<p>Tricky or complicated code blocks should have comments
				4955	before them. Example:</p>
				4956
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	4957	<pre>// Divides result by two, taking into account that x
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	4958	// contains the carry from the add.
				4959	for (int i = 0; i < result->size(); i++) {
				4960	x = (x << 8) + (*result)[i];
				4961	(*result)[i] = x >> 1;
				4962	x &= 1;
				4963	}
				4964	</pre>
				4965
				4966	<h4 class="stylepoint_subsection">Line Comments</h4>
				4967
				4968	<p>Also, lines that are non-obvious should get a comment
				4969	at the end of the line. These end-of-line comments should
				4970	be separated from the code by 2 spaces. Example:</p>
				4971
				4972	<pre>// If we have enough memory, mmap the data portion too.
				4973	mmap_budget = max<int64>(0, mmap_budget - index_->length());
				4974	if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock))
				4975	return; // Error already logged.
				4976	</pre>
				4977
				4978	<p>Note that there are both comments that describe what
				4979	the code is doing, and comments that mention that an
				4980	error has already been logged when the function
				4981	returns.</p>
				4982
				4983	<p>If you have several comments on subsequent lines, it
				4984	can often be more readable to line them up:</p>
				4985
				4986	<pre>DoSomething(); // Comment here so the comments line up.
				4987	DoSomethingElseThatIsLonger(); // Two spaces between the code and the comment.
				4988	{ // One space before comment when opening a new scope is allowed,
				4989	// thus the comment lines up with the following comments and code.
				4990	DoSomethingElse(); // Two spaces before line comments normally.
				4991	}
				4992	std::vector<string> list{
				4993	// Comments in braced lists describe the next element...
				4994	"First item",
				4995	// .. and should be aligned appropriately.
				4996	"Second item"};
				4997	DoSomething(); /* For trailing block comments, one space is fine. */
				4998	</pre>
				4999
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	5000	<h4 class="stylepoint_subsection" id="Function_Argument_Comments">Function Argument Comments</h4>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5001
				5002	<p>When the meaning of a function argument is nonobvious, consider
				5003	one of the following remedies:</p>
				5004
				5005	<ul>
				5006	<li>If the argument is a literal constant, and the same constant is
				5007	used in multiple function calls in a way that tacitly assumes they're
				5008	the same, you should use a named constant to make that constraint
				5009	explicit, and to guarantee that it holds.</li>
				5010
				5011	<li>Consider changing the function signature to replace a <code>bool</code>
				5012	argument with an <code>enum</code> argument. This will make the argument
				5013	values self-describing.</li>
				5014
				5015	<li>For functions that have several configuration options, consider
				5016	defining a single class or struct to hold all the options
				5017	,
				5018	and pass an instance of that.
				5019	This approach has several advantages. Options are referenced by name
				5020	at the call site, which clarifies their meaning. It also reduces
				5021	function argument count, which makes function calls easier to read and
				5022	write. As an added benefit, you don't have to change call sites when
				5023	you add another option.
				5024	</li>
				5025
				5026	<li>Replace large or complex nested expressions with named variables.</li>
				5027
				5028	<li>As a last resort, use comments to clarify argument meanings at the
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	5029	call site. </li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5030	</ul>
				5031
				5032	Consider the following example:
				5033
				5034	<pre class="badcode">// What are these arguments?
				5035	const DecimalNumber product = CalculateProduct(values, 7, false, nullptr);
				5036	</pre>
				5037
				5038	<p>versus:</p>
				5039
				5040	<pre>ProductOptions options;
				5041	options.set_precision_decimals(7);
				5042	options.set_use_cache(ProductOptions::kDontUseCache);
				5043	const DecimalNumber product =
				5044	CalculateProduct(values, options, /completion_callback=/nullptr);
				5045	</pre>
				5046
				5047	<h4 class="stylepoint_subsection">Don'ts</h4>
				5048
				5049	<p>Do not state the obvious. In particular, don't literally describe what
				5050	code does, unless the behavior is nonobvious to a reader who understands
				5051	C++ well. Instead, provide higher level comments that describe <i>why</i>
				5052	the code does what it does, or make the code self describing.</p>
				5053
				5054	Compare this:
				5055
				5056	<pre class="badcode">// Find the element in the vector. <-- Bad: obvious!
				5057	auto iter = std::find(v.begin(), v.end(), element);
				5058	if (iter != v.end()) {
				5059	Process(element);
				5060	}
				5061	</pre>
				5062
				5063	To this:
				5064
				5065	<pre>// Process "element" unless it was already processed.
				5066	auto iter = std::find(v.begin(), v.end(), element);
				5067	if (iter != v.end()) {
				5068	Process(element);
				5069	}
				5070	</pre>
				5071
				5072	Self-describing code doesn't need a comment. The comment from
				5073	the example above would be obvious:
				5074
				5075	<pre>if (!IsAlreadyProcessed(element)) {
				5076	Process(element);
				5077	}
				5078	</pre>
				5079
				5080	</div>
				5081
				5082	<h3 id="Punctuation,_Spelling_and_Grammar">Punctuation, Spelling and Grammar</h3>
				5083
				5084	<div class="summary">
				5085	<p>Pay attention to punctuation, spelling, and grammar; it is
				5086	easier to read well-written comments than badly written
				5087	ones.</p>
				5088	</div>
				5089
				5090	<div class="stylebody">
				5091
				5092	<p>Comments should be as readable as narrative text, with
				5093	proper capitalization and punctuation. In many cases,
				5094	complete sentences are more readable than sentence
				5095	fragments. Shorter comments, such as comments at the end
				5096	of a line of code, can sometimes be less formal, but you
				5097	should be consistent with your style.</p>
				5098
				5099	<p>Although it can be frustrating to have a code reviewer
				5100	point out that you are using a comma when you should be
				5101	using a semicolon, it is very important that source code
				5102	maintain a high level of clarity and readability. Proper
				5103	punctuation, spelling, and grammar help with that
				5104	goal.</p>
				5105
				5106	</div>
				5107
				5108	<h3 id="TODO_Comments">TODO Comments</h3>
				5109
				5110	<div class="summary">
				5111	<p>Use <code>TODO</code> comments for code that is temporary,
				5112	a short-term solution, or good-enough but not perfect.</p>
				5113	</div>
				5114
				5115	<div class="stylebody">
				5116
				5117	<p><code>TODO</code>s should include the string
				5118	<code>TODO</code> in all caps, followed by the
				5119
				5120	name, e-mail address, bug ID, or other
				5121	identifier
				5122	of the person or issue with the best context
				5123	about the problem referenced by the <code>TODO</code>. The
				5124	main purpose is to have a consistent <code>TODO</code> that
				5125	can be searched to find out how to get more details upon
				5126	request. A <code>TODO</code> is not a commitment that the
				5127	person referenced will fix the problem. Thus when you create
				5128	a <code>TODO</code> with a name, it is almost always your
				5129	name that is given.</p>
				5130
				5131
				5132
				5133	<div>
				5134	<pre>// TODO(kl@gmail.com): Use a "*" here for concatenation operator.
				5135	// TODO(Zeke) change this to use relations.
				5136	// TODO(bug 12345): remove the "Last visitors" feature
				5137	</pre>
				5138	</div>
				5139
				5140	<p>If your <code>TODO</code> is of the form "At a future
				5141	date do something" make sure that you either include a
				5142	very specific date ("Fix by November 2005") or a very
				5143	specific event ("Remove this code when all clients can
				5144	handle XML responses.").</p>
				5145
				5146	</div>
				5147
				5148	<h3 id="Deprecation_Comments">Deprecation Comments</h3>
				5149
				5150	<div class="summary">
				5151	<p>Mark deprecated interface points with <code>DEPRECATED</code>
				5152	comments.</p>
				5153	</div>
				5154
				5155	<div class="stylebody">
				5156
				5157	<p>You can mark an interface as deprecated by writing a
				5158	comment containing the word <code>DEPRECATED</code> in
				5159	all caps. The comment goes either before the declaration
				5160	of the interface or on the same line as the
				5161	declaration.</p>
				5162
				5163
				5164
				5165	<p>After the word
				5166	<code>DEPRECATED</code>, write your name, e-mail address,
				5167	or other identifier in parentheses.</p>
				5168
				5169	<p>A deprecation comment must include simple, clear
				5170	directions for people to fix their callsites. In C++, you
				5171	can implement a deprecated function as an inline function
				5172	that calls the new interface point.</p>
				5173
				5174	<p>Marking an interface point <code>DEPRECATED</code>
				5175	will not magically cause any callsites to change. If you
				5176	want people to actually stop using the deprecated
				5177	facility, you will have to fix the callsites yourself or
				5178	recruit a crew to help you.</p>
				5179
				5180	<p>New code should not contain calls to deprecated
				5181	interface points. Use the new interface point instead. If
				5182	you cannot understand the directions, find the person who
				5183	created the deprecation and ask them for help using the
				5184	new interface point.</p>
				5185
				5186
				5187
				5188	</div>
				5189
				5190	<h2 id="Formatting">Formatting</h2>
				5191
				5192	<p>Coding style and formatting are pretty arbitrary, but a
				5193
				5194	project is much easier to follow
				5195	if everyone uses the same style. Individuals may not agree with every
				5196	aspect of the formatting rules, and some of the rules may take
				5197	some getting used to, but it is important that all
				5198
				5199	project contributors follow the
				5200	style rules so that
				5201	they can all read and understand
				5202	everyone's code easily.</p>
				5203
				5204
				5205
				5206	<p>To help you format code correctly, we've
				5207	created a
				5208	<a href="https://raw.githubusercontent.com/google/styleguide/gh-pages/google-c-style.el">
				5209	settings file for emacs</a>.</p>
				5210
				5211	<h3 id="Line_Length">Line Length</h3>
				5212
				5213	<div class="summary">
				5214	<p>Each line of text in your code should be at most 80
				5215	characters long.</p>
				5216	</div>
				5217
				5218	<div class="stylebody">
				5219
				5220
				5221
				5222	<p>We recognize that this rule is
				5223	controversial, but so much existing code already adheres
				5224	to it, and we feel that consistency is important.</p>
				5225
				5226	<div class="pros">
				5227	<p>Those who favor this rule
				5228	argue that it is rude to force them to resize
				5229	their windows and there is no need for anything longer.
				5230	Some folks are used to having several code windows
				5231	side-by-side, and thus don't have room to widen their
				5232	windows in any case. People set up their work environment
				5233	assuming a particular maximum window width, and 80
				5234	columns has been the traditional standard. Why change
				5235	it?</p>
				5236	</div>
				5237
				5238	<div class="cons">
				5239	<p>Proponents of change argue that a wider line can make
				5240	code more readable. The 80-column limit is an hidebound
				5241	throwback to 1960s mainframes; modern equipment has wide screens that
				5242	can easily show longer lines.</p>
				5243	</div>
				5244
				5245	<div class="decision">
				5246	<p> 80 characters is the maximum.</p>
				5247
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	5248	<p>A line may exceed 80 characters if it is</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5249
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	5250	<ul>
				5251	<li>a comment line which is not feasible to split without harming
				5252	readability, ease of cut and paste or auto-linking -- e.g. if a line
				5253	contains an example command or a literal URL longer than 80 characters.</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5254
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	5255	<li>a raw-string literal with content that exceeds 80 characters. Except for
				5256	test code, such literals should appear near the top of a file.</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5257
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	5258	<li>an include statement.</li>
				5259
				5260	<li>a <a href="#The__define_Guard">header guard</a></li>
				5261
				5262	<li>a using-declaration</li>
				5263	</ul>
				5264
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5265	</div>
				5266
				5267	</div>
				5268
				5269	<h3 id="Non-ASCII_Characters">Non-ASCII Characters</h3>
				5270
				5271	<div class="summary">
				5272	<p>Non-ASCII characters should be rare, and must use UTF-8
				5273	formatting.</p>
				5274	</div>
				5275
				5276	<div class="stylebody">
				5277
				5278	<p>You shouldn't hard-code user-facing text in source,
				5279	even English, so use of non-ASCII characters should be
				5280	rare. However, in certain cases it is appropriate to
				5281	include such words in your code. For example, if your
				5282	code parses data files from foreign sources, it may be
				5283	appropriate to hard-code the non-ASCII string(s) used in
				5284	those data files as delimiters. More commonly, unittest
				5285	code (which does not need to be localized) might
				5286	contain non-ASCII strings. In such cases, you should use
				5287	UTF-8, since that is an encoding
				5288	understood by most tools able to handle more than just
				5289	ASCII.</p>
				5290
				5291	<p>Hex encoding is also OK, and encouraged where it
				5292	enhances readability — for example,
				5293	<code>"\xEF\xBB\xBF"</code>, or, even more simply,
				5294	<code>u8"\uFEFF"</code>, is the Unicode zero-width
				5295	no-break space character, which would be invisible if
				5296	included in the source as straight UTF-8.</p>
				5297
				5298	<p>Use the <code>u8</code> prefix
				5299	to guarantee that a string literal containing
				5300	<code>\uXXXX</code> escape sequences is encoded as UTF-8.
				5301	Do not use it for strings containing non-ASCII characters
				5302	encoded as UTF-8, because that will produce incorrect
				5303	output if the compiler does not interpret the source file
				5304	as UTF-8. </p>
				5305
				5306	<p>You shouldn't use the C++11 <code>char16_t</code> and
				5307	<code>char32_t</code> character types, since they're for
				5308	non-UTF-8 text. For similar reasons you also shouldn't
				5309	use <code>wchar_t</code> (unless you're writing code that
				5310	interacts with the Windows API, which uses
				5311	<code>wchar_t</code> extensively).</p>
				5312
				5313	</div>
				5314
				5315	<h3 id="Spaces_vs._Tabs">Spaces vs. Tabs</h3>
				5316
				5317	<div class="summary">
				5318	<p>Use only spaces, and indent 2 spaces at a time.</p>
				5319	</div>
				5320
				5321	<div class="stylebody">
				5322
				5323	<p>We use spaces for indentation. Do not use tabs in your
				5324	code. You should set your editor to emit spaces when you
				5325	hit the tab key.</p>
				5326
				5327	</div>
				5328
				5329	<h3 id="Function_Declarations_and_Definitions">Function Declarations and Definitions</h3>
				5330
				5331	<div class="summary">
				5332	<p>Return type on the same line as function name, parameters
				5333	on the same line if they fit. Wrap parameter lists which do
				5334	not fit on a single line as you would wrap arguments in a
				5335	<a href="#Function_Calls">function call</a>.</p>
				5336	</div>
				5337
				5338	<div class="stylebody">
				5339
				5340	<p>Functions look like this:</p>
				5341
				5342
				5343	<pre>ReturnType ClassName::FunctionName(Type par_name1, Type par_name2) {
				5344	DoSomething();
				5345	...
				5346	}
				5347	</pre>
				5348
				5349	<p>If you have too much text to fit on one line:</p>
				5350
				5351	<pre>ReturnType ClassName::ReallyLongFunctionName(Type par_name1, Type par_name2,
				5352	Type par_name3) {
				5353	DoSomething();
				5354	...
				5355	}
				5356	</pre>
				5357
				5358	<p>or if you cannot fit even the first parameter:</p>
				5359
				5360	<pre>ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
				5361	Type par_name1, // 4 space indent
				5362	Type par_name2,
				5363	Type par_name3) {
				5364	DoSomething(); // 2 space indent
				5365	...
				5366	}
				5367	</pre>
				5368
				5369	<p>Some points to note:</p>
				5370
				5371	<ul>
				5372	<li>Choose good parameter names.</li>
				5373
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	5374	<li>A parameter name may be omitted only if the parameter is not used in the
				5375	function's definition.</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5376
				5377	<li>If you cannot fit the return type and the function
				5378	name on a single line, break between them.</li>
				5379
				5380	<li>If you break after the return type of a function
				5381	declaration or definition, do not indent.</li>
				5382
				5383	<li>The open parenthesis is always on the same line as
				5384	the function name.</li>
				5385
				5386	<li>There is never a space between the function name
				5387	and the open parenthesis.</li>
				5388
				5389	<li>There is never a space between the parentheses and
				5390	the parameters.</li>
				5391
				5392	<li>The open curly brace is always on the end of the last line of the function
				5393	declaration, not the start of the next line.</li>
				5394
				5395	<li>The close curly brace is either on the last line by
				5396	itself or on the same line as the open curly brace.</li>
				5397
				5398	<li>There should be a space between the close
				5399	parenthesis and the open curly brace.</li>
				5400
				5401	<li>All parameters should be aligned if possible.</li>
				5402
				5403	<li>Default indentation is 2 spaces.</li>
				5404
				5405	<li>Wrapped parameters have a 4 space indent.</li>
				5406	</ul>
				5407
				5408	<p>Unused parameters that are obvious from context may be omitted:</p>
				5409
				5410	<pre>class Foo {
				5411	public:
				5412	Foo(Foo&&);
				5413	Foo(const Foo&);
				5414	Foo& operator=(Foo&&);
				5415	Foo& operator=(const Foo&);
				5416	};
				5417	</pre>
				5418
				5419	<p>Unused parameters that might not be obvious should comment out the variable
				5420	name in the function definition:</p>
				5421
				5422	<pre>class Shape {
				5423	public:
				5424	virtual void Rotate(double radians) = 0;
				5425	};
				5426
				5427	class Circle : public Shape {
				5428	public:
				5429	void Rotate(double radians) override;
				5430	};
				5431
				5432	void Circle::Rotate(double /radians/) {}
				5433	</pre>
				5434
				5435	<pre class="badcode">// Bad - if someone wants to implement later, it's not clear what the
				5436	// variable means.
				5437	void Circle::Rotate(double) {}
				5438	</pre>
				5439
				5440	<p>Attributes, and macros that expand to attributes, appear at the very
				5441	beginning of the function declaration or definition, before the
				5442	return type:</p>
				5443	<pre>MUST_USE_RESULT bool IsOK();
				5444	</pre>
				5445
				5446	</div>
				5447
				5448	<h3 id="Formatting_Lambda_Expressions">Lambda Expressions</h3>
				5449
				5450	<div class="summary">
				5451	<p>Format parameters and bodies as for any other function, and capture
				5452	lists like other comma-separated lists.</p>
				5453	</div>
				5454
				5455	<div class="stylebody">
				5456	<p>For by-reference captures, do not leave a space between the
				5457	ampersand (&) and the variable name.</p>
				5458	<pre>int x = 0;
				5459	auto x_plus_n = [&x](int n) -> int { return x + n; }
				5460	</pre>
				5461	<p>Short lambdas may be written inline as function arguments.</p>
				5462	<pre>std::set<int> blacklist = {7, 8, 9};
				5463	std::vector<int> digits = {3, 9, 1, 8, 4, 7, 1};
				5464	digits.erase(std::remove_if(digits.begin(), digits.end(), [&blacklist](int i) {
				5465	return blacklist.find(i) != blacklist.end();
				5466	}),
				5467	digits.end());
				5468	</pre>
				5469
				5470	</div>
				5471
				5472	<h3 id="Function_Calls">Function Calls</h3>
				5473
				5474	<div class="summary">
				5475	<p>Either write the call all on a single line, wrap the
				5476	arguments at the parenthesis, or start the arguments on a new
				5477	line indented by four spaces and continue at that 4 space
				5478	indent. In the absence of other considerations, use the
				5479	minimum number of lines, including placing multiple arguments
				5480	on each line where appropriate.</p>
				5481	</div>
				5482
				5483	<div class="stylebody">
				5484
				5485	<p>Function calls have the following format:</p>
				5486	<pre>bool result = DoSomething(argument1, argument2, argument3);
				5487	</pre>
				5488
				5489	<p>If the arguments do not all fit on one line, they
				5490	should be broken up onto multiple lines, with each
				5491	subsequent line aligned with the first argument. Do not
				5492	add spaces after the open paren or before the close
				5493	paren:</p>
				5494	<pre>bool result = DoSomething(averyveryveryverylongargument1,
				5495	argument2, argument3);
				5496	</pre>
				5497
				5498	<p>Arguments may optionally all be placed on subsequent
				5499	lines with a four space indent:</p>
				5500	<pre>if (...) {
				5501	...
				5502	...
				5503	if (...) {
				5504	bool result = DoSomething(
				5505	argument1, argument2, // 4 space indent
				5506	argument3, argument4);
				5507	...
				5508	}
				5509	</pre>
				5510
				5511	<p>Put multiple arguments on a single line to reduce the
				5512	number of lines necessary for calling a function unless
				5513	there is a specific readability problem. Some find that
				5514	formatting with strictly one argument on each line is
				5515	more readable and simplifies editing of the arguments.
				5516	However, we prioritize for the reader over the ease of
				5517	editing arguments, and most readability problems are
				5518	better addressed with the following techniques.</p>
				5519
				5520	<p>If having multiple arguments in a single line decreases
				5521	readability due to the complexity or confusing nature of the
				5522	expressions that make up some arguments, try creating
				5523	variables that capture those arguments in a descriptive name:</p>
				5524	<pre>int my_heuristic = scores[x] * y + bases[x];
				5525	bool result = DoSomething(my_heuristic, x, y, z);
				5526	</pre>
				5527
				5528	<p>Or put the confusing argument on its own line with
				5529	an explanatory comment:</p>
				5530	<pre>bool result = DoSomething(scores[x] * y + bases[x], // Score heuristic.
				5531	x, y, z);
				5532	</pre>
				5533
				5534	<p>If there is still a case where one argument is
				5535	significantly more readable on its own line, then put it on
				5536	its own line. The decision should be specific to the argument
				5537	which is made more readable rather than a general policy.</p>
				5538
				5539	<p>Sometimes arguments form a structure that is important
				5540	for readability. In those cases, feel free to format the
				5541	arguments according to that structure:</p>
				5542	<pre>// Transform the widget by a 3x3 matrix.
				5543	my_widget.Transform(x1, x2, x3,
				5544	y1, y2, y3,
				5545	z1, z2, z3);
				5546	</pre>
				5547
				5548	</div>
				5549
				5550	<h3 id="Braced_Initializer_List_Format">Braced Initializer List Format</h3>
				5551
				5552	<div class="summary">
				5553	<p>Format a <a href="#Braced_Initializer_List">braced initializer list</a>
				5554	exactly like you would format a function call in its place.</p>
				5555	</div>
				5556
				5557	<div class="stylebody">
				5558
				5559	<p>If the braced list follows a name (e.g. a type or
				5560	variable name), format as if the <code>{}</code> were the
				5561	parentheses of a function call with that name. If there
				5562	is no name, assume a zero-length name.</p>
				5563
				5564	<pre>// Examples of braced init list on a single line.
				5565	return {foo, bar};
				5566	functioncall({foo, bar});
				5567	std::pair<int, int> p{foo, bar};
				5568
				5569	// When you have to wrap.
				5570	SomeFunction(
				5571	{"assume a zero-length name before {"},
				5572	some_other_function_parameter);
				5573	SomeType variable{
				5574	some, other, values,
				5575	{"assume a zero-length name before {"},
				5576	SomeOtherType{
				5577	"Very long string requiring the surrounding breaks.",
				5578	some, other values},
				5579	SomeOtherType{"Slightly shorter string",
				5580	some, other, values}};
				5581	SomeType variable{
				5582	"This is too long to fit all in one line"};
				5583	MyType m = { // Here, you could also break before {.
				5584	superlongvariablename1,
				5585	superlongvariablename2,
				5586	{short, interior, list},
				5587	{interiorwrappinglist,
				5588	interiorwrappinglist2}};
				5589	</pre>
				5590
				5591	</div>
				5592
				5593	<h3 id="Conditionals">Conditionals</h3>
				5594
				5595	<div class="summary">
				5596	<p>Prefer no spaces inside parentheses. The <code>if</code>
				5597	and <code>else</code> keywords belong on separate lines.</p>
				5598	</div>
				5599
				5600	<div class="stylebody">
				5601
				5602	<p>There are two acceptable formats for a basic
				5603	conditional statement. One includes spaces between the
				5604	parentheses and the condition, and one does not.</p>
				5605
				5606	<p>The most common form is without spaces. Either is
				5607	fine, but <em>be consistent</em>. If you are modifying a
				5608	file, use the format that is already present. If you are
				5609	writing new code, use the format that the other files in
				5610	that directory or project use. If in doubt and you have
				5611	no personal preference, do not add the spaces.</p>
				5612
				5613	<pre>if (condition) { // no spaces inside parentheses
				5614	... // 2 space indent.
				5615	} else if (...) { // The else goes on the same line as the closing brace.
				5616	...
				5617	} else {
				5618	...
				5619	}
				5620	</pre>
				5621
				5622	<p>If you prefer you may add spaces inside the
				5623	parentheses:</p>
				5624
				5625	<pre>if ( condition ) { // spaces inside parentheses - rare
				5626	... // 2 space indent.
				5627	} else { // The else goes on the same line as the closing brace.
				5628	...
				5629	}
				5630	</pre>
				5631
				5632	<p>Note that in all cases you must have a space between
				5633	the <code>if</code> and the open parenthesis. You must
				5634	also have a space between the close parenthesis and the
				5635	curly brace, if you're using one.</p>
				5636
				5637	<pre class="badcode">if(condition) { // Bad - space missing after IF.
				5638	if (condition){ // Bad - space missing before {.
				5639	if(condition){ // Doubly bad.
				5640	</pre>
				5641
				5642	<pre>if (condition) { // Good - proper space after IF and before {.
				5643	</pre>
				5644
				5645	<p>Short conditional statements may be written on one
				5646	line if this enhances readability. You may use this only
				5647	when the line is brief and the statement does not use the
				5648	<code>else</code> clause.</p>
				5649
				5650	<pre>if (x == kFoo) return new Foo();
				5651	if (x == kBar) return new Bar();
				5652	</pre>
				5653
				5654	<p>This is not allowed when the if statement has an
				5655	<code>else</code>:</p>
				5656
				5657	<pre class="badcode">// Not allowed - IF statement on one line when there is an ELSE clause
				5658	if (x) DoThis();
				5659	else DoThat();
				5660	</pre>
				5661
				5662	<p>In general, curly braces are not required for
				5663	single-line statements, but they are allowed if you like
				5664	them; conditional or loop statements with complex
				5665	conditions or statements may be more readable with curly
				5666	braces. Some
				5667	projects require that an
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	5668	<code>if</code> must always have an accompanying
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5669	brace.</p>
				5670
				5671	<pre>if (condition)
				5672	DoSomething(); // 2 space indent.
				5673
				5674	if (condition) {
				5675	DoSomething(); // 2 space indent.
				5676	}
				5677	</pre>
				5678
				5679	<p>However, if one part of an
				5680	<code>if</code>-<code>else</code> statement uses curly
				5681	braces, the other part must too:</p>
				5682
				5683	<pre class="badcode">// Not allowed - curly on IF but not ELSE
				5684	if (condition) {
				5685	foo;
				5686	} else
				5687	bar;
				5688
				5689	// Not allowed - curly on ELSE but not IF
				5690	if (condition)
				5691	foo;
				5692	else {
				5693	bar;
				5694	}
				5695	</pre>
				5696
				5697	<pre>// Curly braces around both IF and ELSE required because
				5698	// one of the clauses used braces.
				5699	if (condition) {
				5700	foo;
				5701	} else {
				5702	bar;
				5703	}
				5704	</pre>
				5705
				5706	</div>
				5707
				5708	<h3 id="Loops_and_Switch_Statements">Loops and Switch Statements</h3>
				5709
				5710	<div class="summary">
				5711	<p>Switch statements may use braces for blocks. Annotate
				5712	non-trivial fall-through between cases.
				5713	Braces are optional for single-statement loops.
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	5714	Empty loop bodies should use either empty braces or <code>continue</code>.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5715	</div>
				5716
				5717	<div class="stylebody">
				5718
				5719	<p><code>case</code> blocks in <code>switch</code>
				5720	statements can have curly braces or not, depending on
				5721	your preference. If you do include curly braces they
				5722	should be placed as shown below.</p>
				5723
				5724	<p>If not conditional on an enumerated value, switch
				5725	statements should always have a <code>default</code> case
				5726	(in the case of an enumerated value, the compiler will
				5727	warn you if any values are not handled). If the default
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	5728	case should never execute, treat this as an error. For example:
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5729
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	5730	</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5731
				5732	<div>
				5733	<pre>switch (var) {
				5734	case 0: { // 2 space indent
				5735	... // 4 space indent
				5736	break;
				5737	}
				5738	case 1: {
				5739	...
				5740	break;
				5741	}
				5742	default: {
				5743	assert(false);
				5744	}
				5745	}
				5746	</pre>
				5747	</div>
				5748
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	5749	<p>Fall-through from one case label to
				5750	another must be annotated using the
				5751	<code>ABSL_FALLTHROUGH_INTENDED;</code> macro (defined in
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5752
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	5753	<code>absl/base/macros.h</code>).
				5754	<code>ABSL_FALLTHROUGH_INTENDED;</code> should be placed at a
				5755	point of execution where a fall-through to the next case
				5756	label occurs. A common exception is consecutive case
				5757	labels without intervening code, in which case no
				5758	annotation is needed.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5759
Victor Costan	4b9c0c0	2018-02-20 14:58:48 -0800	[diff] [blame]	5760	<div>
				5761	<pre>switch (x) {
				5762	case 41: // No annotation needed here.
				5763	case 43:
				5764	if (dont_be_picky) {
				5765	// Use this instead of or along with annotations in comments.
				5766	ABSL_FALLTHROUGH_INTENDED;
				5767	} else {
				5768	CloseButNoCigar();
				5769	break;
				5770	}
				5771	case 42:
				5772	DoSomethingSpecial();
				5773	ABSL_FALLTHROUGH_INTENDED;
				5774	default:
				5775	DoSomethingGeneric();
				5776	break;
				5777	}
				5778	</pre>
				5779	</div>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5780
				5781	<p> Braces are optional for single-statement loops.</p>
				5782
				5783	<pre>for (int i = 0; i < kSomeNumber; ++i)
				5784	printf("I love you\n");
				5785
				5786	for (int i = 0; i < kSomeNumber; ++i) {
				5787	printf("I take it back\n");
				5788	}
				5789	</pre>
				5790
				5791
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	5792	<p>Empty loop bodies should use either an empty pair of braces or
				5793	<code>continue</code> with no braces, rather than a single semicolon.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5794
				5795	<pre>while (condition) {
				5796	// Repeat test until it returns false.
				5797	}
				5798	for (int i = 0; i < kSomeNumber; ++i) {} // Good - one newline is also OK.
				5799	while (condition) continue; // Good - continue indicates no logic.
				5800	</pre>
				5801
				5802	<pre class="badcode">while (condition); // Bad - looks like part of do/while loop.
				5803	</pre>
				5804
				5805	</div>
				5806
				5807	<h3 id="Pointer_and_Reference_Expressions">Pointer and Reference Expressions</h3>
				5808
				5809	<div class="summary">
				5810	<p>No spaces around period or arrow. Pointer operators do not
				5811	have trailing spaces.</p>
				5812	</div>
				5813
				5814	<div class="stylebody">
				5815
				5816	<p>The following are examples of correctly-formatted
				5817	pointer and reference expressions:</p>
				5818
				5819	<pre>x = *p;
				5820	p = &x;
				5821	x = r.y;
				5822	x = r->y;
				5823	</pre>
				5824
				5825	<p>Note that:</p>
				5826
				5827	<ul>
				5828	<li>There are no spaces around the period or arrow when
				5829	accessing a member.</li>
				5830
				5831	<li>Pointer operators have no space after the
				5832	<code>*</code> or <code>&</code>.</li>
				5833	</ul>
				5834
				5835	<p>When declaring a pointer variable or argument, you may
				5836	place the asterisk adjacent to either the type or to the
				5837	variable name:</p>
				5838
				5839	<pre>// These are fine, space preceding.
				5840	char *c;
				5841	const string &str;
				5842
				5843	// These are fine, space following.
				5844	char* c;
				5845	const string& str;
				5846	</pre>
				5847
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	5848	<p>You should do this consistently within a single
				5849	file,
				5850	so, when modifying an existing file, use the style in
				5851	that file.</p>
				5852
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5853	It is allowed (if unusual) to declare multiple variables in the same
				5854	declaration, but it is disallowed if any of those have pointer or
				5855	reference decorations. Such declarations are easily misread.
				5856	<pre>// Fine if helpful for readability.
				5857	int x, y;
				5858	</pre>
				5859	<pre class="badcode">int x, y; // Disallowed - no & or in multiple declaration
				5860	char * c; // Bad - spaces on both sides of *
				5861	const string & str; // Bad - spaces on both sides of &
				5862	</pre>
				5863
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5864	</div>
				5865
				5866	<h3 id="Boolean_Expressions">Boolean Expressions</h3>
				5867
				5868	<div class="summary">
				5869	<p>When you have a boolean expression that is longer than the
				5870	<a href="#Line_Length">standard line length</a>, be
				5871	consistent in how you break up the lines.</p>
				5872	</div>
				5873
				5874	<div class="stylebody">
				5875
				5876	<p>In this example, the logical AND operator is always at
				5877	the end of the lines:</p>
				5878
				5879	<pre>if (this_one_thing > this_other_thing &&
				5880	a_third_thing == a_fourth_thing &&
				5881	yet_another && last_one) {
				5882	...
				5883	}
				5884	</pre>
				5885
				5886	<p>Note that when the code wraps in this example, both of
				5887	the <code>&&</code> logical AND operators are at
				5888	the end of the line. This is more common in Google code,
				5889	though wrapping all operators at the beginning of the
				5890	line is also allowed. Feel free to insert extra
				5891	parentheses judiciously because they can be very helpful
				5892	in increasing readability when used
				5893	appropriately. Also note that you should always use
				5894	the punctuation operators, such as
				5895	<code>&&</code> and <code>~</code>, rather than
				5896	the word operators, such as <code>and</code> and
				5897	<code>compl</code>.</p>
				5898
				5899	</div>
				5900
				5901	<h3 id="Return_Values">Return Values</h3>
				5902
				5903	<div class="summary">
				5904	<p>Do not needlessly surround the <code>return</code>
				5905	expression with parentheses.</p>
				5906	</div>
				5907
				5908	<div class="stylebody">
				5909
				5910	<p>Use parentheses in <code>return expr;</code> only
				5911	where you would use them in <code>x = expr;</code>.</p>
				5912
				5913	<pre>return result; // No parentheses in the simple case.
				5914	// Parentheses OK to make a complex expression more readable.
				5915	return (some_long_condition &&
				5916	another_condition);
				5917	</pre>
				5918
				5919	<pre class="badcode">return (value); // You wouldn't write var = (value);
				5920	return(result); // return is not a function!
				5921	</pre>
				5922
				5923	</div>
				5924
				5925
				5926
				5927	<h3 id="Variable_and_Array_Initialization">Variable and Array Initialization</h3>
				5928
				5929	<div class="summary">
				5930	<p>Your choice of <code>=</code>, <code>()</code>, or
				5931	<code>{}</code>.</p>
				5932	</div>
				5933
				5934	<div class="stylebody">
				5935
				5936	<p>You may choose between <code>=</code>,
				5937	<code>()</code>, and <code>{}</code>; the following are
				5938	all correct:</p>
				5939
				5940	<pre>int x = 3;
				5941	int x(3);
				5942	int x{3};
				5943	string name = "Some Name";
				5944	string name("Some Name");
				5945	string name{"Some Name"};
				5946	</pre>
				5947
				5948	<p>Be careful when using a braced initialization list <code>{...}</code>
				5949	on a type with an <code>std::initializer_list</code> constructor.
				5950	A nonempty <i>braced-init-list</i> prefers the
				5951	<code>std::initializer_list</code> constructor whenever
				5952	possible. Note that empty braces <code>{}</code> are special, and
				5953	will call a default constructor if available. To force the
				5954	non-<code>std::initializer_list</code> constructor, use parentheses
				5955	instead of braces.</p>
				5956
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	5957	<pre>std::vector<int> v(100, 1); // A vector containing 100 items: All 1s.
				5958	std::vector<int> v{100, 1}; // A vector containing 2 items: 100 and 1.
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	5959	</pre>
				5960
				5961	<p>Also, the brace form prevents narrowing of integral
				5962	types. This can prevent some types of programming
				5963	errors.</p>
				5964
				5965	<pre>int pi(3.14); // OK -- pi == 3.
				5966	int pi{3.14}; // Compile error: narrowing conversion.
				5967	</pre>
				5968
				5969	</div>
				5970
				5971	<h3 id="Preprocessor_Directives">Preprocessor Directives</h3>
				5972
				5973	<div class="summary">
				5974	<p>The hash mark that starts a preprocessor directive should
				5975	always be at the beginning of the line.</p>
				5976	</div>
				5977
				5978	<div class="stylebody">
				5979
				5980	<p>Even when preprocessor directives are within the body
				5981	of indented code, the directives should start at the
				5982	beginning of the line.</p>
				5983
				5984	<pre>// Good - directives at beginning of line
				5985	if (lopsided_score) {
				5986	#if DISASTER_PENDING // Correct -- Starts at beginning of line
				5987	DropEverything();
				5988	# if NOTIFY // OK but not required -- Spaces after #
				5989	NotifyClient();
				5990	# endif
				5991	#endif
				5992	BackToNormal();
				5993	}
				5994	</pre>
				5995
				5996	<pre class="badcode">// Bad - indented directives
				5997	if (lopsided_score) {
				5998	#if DISASTER_PENDING // Wrong! The "#if" should be at beginning of line
				5999	DropEverything();
				6000	#endif // Wrong! Do not indent "#endif"
				6001	BackToNormal();
				6002	}
				6003	</pre>
				6004
				6005	</div>
				6006
				6007	<h3 id="Class_Format">Class Format</h3>
				6008
				6009	<div class="summary">
				6010	<p>Sections in <code>public</code>, <code>protected</code> and
				6011	<code>private</code> order, each indented one space.</p>
				6012	</div>
				6013
				6014	<div class="stylebody">
				6015
				6016	<p>The basic format for a class definition (lacking the
				6017	comments, see <a href="#Class_Comments">Class
				6018	Comments</a> for a discussion of what comments are
				6019	needed) is:</p>
				6020
				6021	<pre>class MyClass : public OtherClass {
				6022	public: // Note the 1 space indent!
				6023	MyClass(); // Regular 2 space indent.
				6024	explicit MyClass(int var);
				6025	~MyClass() {}
				6026
				6027	void SomeFunction();
				6028	void SomeFunctionThatDoesNothing() {
				6029	}
				6030
				6031	void set_some_var(int var) { some_var_ = var; }
				6032	int some_var() const { return some_var_; }
				6033
				6034	private:
				6035	bool SomeInternalFunction();
				6036
				6037	int some_var_;
				6038	int some_other_var_;
				6039	};
				6040	</pre>
				6041
				6042	<p>Things to note:</p>
				6043
				6044	<ul>
				6045	<li>Any base class name should be on the same line as
				6046	the subclass name, subject to the 80-column limit.</li>
				6047
				6048	<li>The <code>public:</code>, <code>protected:</code>,
				6049	and <code>private:</code> keywords should be indented
				6050	one space.</li>
				6051
				6052	<li>Except for the first instance, these keywords
				6053	should be preceded by a blank line. This rule is
				6054	optional in small classes.</li>
				6055
				6056	<li>Do not leave a blank line after these
				6057	keywords.</li>
				6058
				6059	<li>The <code>public</code> section should be first,
				6060	followed by the <code>protected</code> and finally the
				6061	<code>private</code> section.</li>
				6062
				6063	<li>See <a href="#Declaration_Order">Declaration
				6064	Order</a> for rules on ordering declarations within
				6065	each of these sections.</li>
				6066	</ul>
				6067
				6068	</div>
				6069
				6070	<h3 id="Constructor_Initializer_Lists">Constructor Initializer Lists</h3>
				6071
				6072	<div class="summary">
				6073	<p>Constructor initializer lists can be all on one line or
				6074	with subsequent lines indented four spaces.</p>
				6075	</div>
				6076
				6077	<div class="stylebody">
				6078
				6079	<p>The acceptable formats for initializer lists are:</p>
				6080
				6081	<pre>// When everything fits on one line:
				6082	MyClass::MyClass(int var) : some_var_(var) {
				6083	DoSomething();
				6084	}
				6085
				6086	// If the signature and initializer list are not all on one line,
				6087	// you must wrap before the colon and indent 4 spaces:
				6088	MyClass::MyClass(int var)
				6089	: some_var_(var), some_other_var_(var + 1) {
				6090	DoSomething();
				6091	}
				6092
				6093	// When the list spans multiple lines, put each member on its own line
				6094	// and align them:
				6095	MyClass::MyClass(int var)
				6096	: some_var_(var), // 4 space indent
				6097	some_other_var_(var + 1) { // lined up
				6098	DoSomething();
				6099	}
				6100
				6101	// As with any other code block, the close curly can be on the same
				6102	// line as the open curly, if it fits.
				6103	MyClass::MyClass(int var)
				6104	: some_var_(var) {}
				6105	</pre>
				6106
				6107	</div>
				6108
				6109	<h3 id="Namespace_Formatting">Namespace Formatting</h3>
				6110
				6111	<div class="summary">
				6112	<p>The contents of namespaces are not indented.</p>
				6113	</div>
				6114
				6115	<div class="stylebody">
				6116
				6117	<p><a href="#Namespaces">Namespaces</a> do not add an
				6118	extra level of indentation. For example, use:</p>
				6119
				6120	<pre>namespace {
				6121
				6122	void foo() { // Correct. No extra indentation within namespace.
				6123	...
				6124	}
				6125
				6126	} // namespace
				6127	</pre>
				6128
				6129	<p>Do not indent within a namespace:</p>
				6130
				6131	<pre class="badcode">namespace {
				6132
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	6133	// Wrong! Indented when it should not be.
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	6134	void foo() {
				6135	...
				6136	}
				6137
				6138	} // namespace
				6139	</pre>
				6140
				6141	<p>When declaring nested namespaces, put each namespace
				6142	on its own line.</p>
				6143
				6144	<pre>namespace foo {
				6145	namespace bar {
				6146	</pre>
				6147
				6148	</div>
				6149
				6150	<h3 id="Horizontal_Whitespace">Horizontal Whitespace</h3>
				6151
				6152	<div class="summary">
				6153	<p>Use of horizontal whitespace depends on location. Never put
				6154	trailing whitespace at the end of a line.</p>
				6155	</div>
				6156
				6157	<div class="stylebody">
				6158
				6159	<h4 class="stylepoint_subsection">General</h4>
				6160
				6161	<pre>void f(bool b) { // Open braces should always have a space before them.
				6162	...
				6163	int i = 0; // Semicolons usually have no space before them.
				6164	// Spaces inside braces for braced-init-list are optional. If you use them,
				6165	// put them on both sides!
				6166	int x[] = { 0 };
				6167	int x[] = {0};
				6168
				6169	// Spaces around the colon in inheritance and initializer lists.
				6170	class Foo : public Bar {
				6171	public:
				6172	// For inline function implementations, put spaces between the braces
				6173	// and the implementation itself.
				6174	Foo(int b) : Bar(), baz_(b) {} // No spaces inside empty braces.
				6175	void Reset() { baz_ = 0; } // Spaces separating braces from implementation.
				6176	...
				6177	</pre>
				6178
				6179	<p>Adding trailing whitespace can cause extra work for
				6180	others editing the same file, when they merge, as can
				6181	removing existing trailing whitespace. So: Don't
				6182	introduce trailing whitespace. Remove it if you're
				6183	already changing that line, or do it in a separate
				6184	clean-up
				6185	operation (preferably when no-one
				6186	else is working on the file).</p>
				6187
				6188	<h4 class="stylepoint_subsection">Loops and Conditionals</h4>
				6189
				6190	<pre>if (b) { // Space after the keyword in conditions and loops.
				6191	} else { // Spaces around else.
				6192	}
				6193	while (test) {} // There is usually no space inside parentheses.
				6194	switch (i) {
				6195	for (int i = 0; i < 5; ++i) {
				6196	// Loops and conditions may have spaces inside parentheses, but this
				6197	// is rare. Be consistent.
				6198	switch ( i ) {
				6199	if ( test ) {
				6200	for ( int i = 0; i < 5; ++i ) {
				6201	// For loops always have a space after the semicolon. They may have a space
				6202	// before the semicolon, but this is rare.
				6203	for ( ; i < 5 ; ++i) {
				6204	...
				6205
				6206	// Range-based for loops always have a space before and after the colon.
				6207	for (auto x : counts) {
				6208	...
				6209	}
				6210	switch (i) {
				6211	case 1: // No space before colon in a switch case.
				6212	...
				6213	case 2: break; // Use a space after a colon if there's code after it.
				6214	</pre>
				6215
				6216	<h4 class="stylepoint_subsection">Operators</h4>
				6217
				6218	<pre>// Assignment operators always have spaces around them.
				6219	x = 0;
				6220
				6221	// Other binary operators usually have spaces around them, but it's
				6222	// OK to remove spaces around factors. Parentheses should have no
				6223	// internal padding.
				6224	v = w * x + y / z;
				6225	v = w*x + y/z;
				6226	v = w * (x + z);
				6227
				6228	// No spaces separating unary operators and their arguments.
				6229	x = -5;
				6230	++x;
				6231	if (x && !y)
				6232	...
				6233	</pre>
				6234
				6235	<h4 class="stylepoint_subsection">Templates and Casts</h4>
				6236
				6237	<pre>// No spaces inside the angle brackets (< and >), before
				6238	// <, or between >( in a cast
				6239	std::vector<string> x;
				6240	y = static_cast<char*>(x);
				6241
				6242	// Spaces between type and pointer are OK, but be consistent.
				6243	std::vector<char *> x;
				6244	</pre>
				6245
				6246	</div>
				6247
				6248	<h3 id="Vertical_Whitespace">Vertical Whitespace</h3>
				6249
				6250	<div class="summary">
				6251	<p>Minimize use of vertical whitespace.</p>
				6252	</div>
				6253
				6254	<div class="stylebody">
				6255
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	6256	<p>This is more a principle than a rule: don't use blank lines when
				6257	you don't have to. In particular, don't put more than one or two blank
				6258	lines between functions, resist starting functions with a blank line,
				6259	don't end functions with a blank line, and be sparing with your use of
				6260	blank lines. A blank line within a block of code serves like a
				6261	paragraph break in prose: visually separating two thoughts.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	6262
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	6263	<p>The basic principle is: The more code that fits on one screen, the
				6264	easier it is to follow and understand the control flow of the
				6265	program. Use whitespace purposefully to provide separation in that
				6266	flow.</p>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	6267
				6268	<p>Some rules of thumb to help when blank lines may be
				6269	useful:</p>
				6270
				6271	<ul>
				6272	<li>Blank lines at the beginning or end of a function
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	6273	do not help readability.</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	6274
				6275	<li>Blank lines inside a chain of if-else blocks may
				6276	well help readability.</li>
Victor Costan	b89a775	2018-07-31 10:17:48 -0700	[diff] [blame^]	6277
				6278	<li>A blank line before a comment line usually helps
				6279	readability — the introduction of a new comment suggests
				6280	the start of a new thought, and the blank line makes it clear
				6281	that the comment goes with the following thing instead of the
				6282	preceding.</li>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	6283	</ul>
				6284
				6285	</div>
				6286
				6287	<h2 id="Exceptions_to_the_Rules">Exceptions to the Rules</h2>
				6288
				6289	<p>The coding conventions described above are mandatory.
				6290	However, like all good rules, these sometimes have exceptions,
				6291	which we discuss here.</p>
				6292
				6293
				6294
				6295	<div>
				6296	<h3 id="Existing_Non-conformant_Code">Existing Non-conformant Code</h3>
				6297
				6298	<div class="summary">
				6299	<p>You may diverge from the rules when dealing with code that
				6300	does not conform to this style guide.</p>
				6301	</div>
				6302
				6303	<div class="stylebody">
				6304
				6305	<p>If you find yourself modifying code that was written
				6306	to specifications other than those presented by this
				6307	guide, you may have to diverge from these rules in order
				6308	to stay consistent with the local conventions in that
				6309	code. If you are in doubt about how to do this, ask the
				6310	original author or the person currently responsible for
				6311	the code. Remember that <em>consistency</em> includes
				6312	local consistency, too.</p>
				6313
				6314	</div>
				6315	</div>
				6316
				6317
				6318
				6319	<h3 id="Windows_Code">Windows Code</h3>
				6320
				6321	<div class="summary">
				6322	<p> Windows
				6323	programmers have developed their own set of coding
				6324	conventions, mainly derived from the conventions in Windows
				6325	headers and other Microsoft code. We want to make it easy
				6326	for anyone to understand your code, so we have a single set
				6327	of guidelines for everyone writing C++ on any platform.</p>
				6328	</div>
				6329
				6330	<div class="stylebody">
				6331	<p>It is worth reiterating a few of the guidelines that
				6332	you might forget if you are used to the prevalent Windows
				6333	style:</p>
				6334
				6335	<ul>
				6336	<li>Do not use Hungarian notation (for example, naming
				6337	an integer <code>iNum</code>). Use the Google naming
				6338	conventions, including the <code>.cc</code> extension
				6339	for source files.</li>
				6340
				6341	<li>Windows defines many of its own synonyms for
				6342	primitive types, such as <code>DWORD</code>,
				6343	<code>HANDLE</code>, etc. It is perfectly acceptable,
				6344	and encouraged, that you use these types when calling
				6345	Windows API functions. Even so, keep as close as you
				6346	can to the underlying C++ types. For example, use
				6347	<code>const TCHAR *</code> instead of
				6348	<code>LPCTSTR</code>.</li>
				6349
				6350	<li>When compiling with Microsoft Visual C++, set the
				6351	compiler to warning level 3 or higher, and treat all
				6352	warnings as errors.</li>
				6353
				6354	<li>Do not use <code>#pragma once</code>; instead use
				6355	the standard Google include guards. The path in the
				6356	include guards should be relative to the top of your
				6357	project tree.</li>
				6358
				6359	<li>In fact, do not use any nonstandard extensions,
				6360	like <code>#pragma</code> and <code>__declspec</code>,
				6361	unless you absolutely must. Using
				6362	<code>__declspec(dllimport)</code> and
				6363	<code>__declspec(dllexport)</code> is allowed; however,
				6364	you must use them through macros such as
				6365	<code>DLLIMPORT</code> and <code>DLLEXPORT</code>, so
				6366	that someone can easily disable the extensions if they
				6367	share the code.</li>
				6368	</ul>
				6369
				6370	<p>However, there are just a few rules that we
				6371	occasionally need to break on Windows:</p>
				6372
				6373	<ul>
				6374	<li>Normally we <a href="#Multiple_Inheritance">forbid
				6375	the use of multiple implementation inheritance</a>;
				6376	however, it is required when using COM and some ATL/WTL
				6377	classes. You may use multiple implementation
				6378	inheritance to implement COM or ATL/WTL classes and
				6379	interfaces.</li>
				6380
				6381	<li>Although you should not use exceptions in your own
				6382	code, they are used extensively in the ATL and some
				6383	STLs, including the one that comes with Visual C++.
				6384	When using the ATL, you should define
				6385	<code>_ATL_NO_EXCEPTIONS</code> to disable exceptions.
				6386	You should investigate whether you can also disable
				6387	exceptions in your STL, but if not, it is OK to turn on
				6388	exceptions in the compiler. (Note that this is only to
				6389	get the STL to compile. You should still not write
				6390	exception handling code yourself.)</li>
				6391
				6392	<li>The usual way of working with precompiled headers
				6393	is to include a header file at the top of each source
				6394	file, typically with a name like <code>StdAfx.h</code>
				6395	or <code>precompile.h</code>. To make your code easier
				6396	to share with other projects, avoid including this file
				6397	explicitly (except in <code>precompile.cc</code>), and
				6398	use the <code>/FI</code> compiler option to include the
				6399	file automatically.</li>
				6400
				6401	<li>Resource headers, which are usually named
				6402	<code>resource.h</code> and contain only macros, do not
				6403	need to conform to these style guidelines.</li>
				6404	</ul>
				6405
				6406	</div>
				6407
Victor Costan	6dfd9d9	2018-02-05 18:30:35 -0800	[diff] [blame]	6408	<h2 id="Parting_Words">Parting Words</h2>
Ted Osborne	505ba68	2018-01-30 12:36:50 -0500	[diff] [blame]	6409
				6410	<p>Use common sense and <em>BE CONSISTENT</em>.</p>
				6411
				6412	<p>If you are editing code, take a few minutes to look at the
				6413	code around you and determine its style. If they use spaces
				6414	around their <code>if</code> clauses, you should, too. If their
				6415	comments have little boxes of stars around them, make your
				6416	comments have little boxes of stars around them too.</p>
				6417
				6418	<p>The point of having style guidelines is to have a common
				6419	vocabulary of coding so people can concentrate on what you are
				6420	saying, rather than on how you are saying it. We present global
				6421	style rules here so people know the vocabulary. But local style
				6422	is also important. If code you add to a file looks drastically
				6423	different from the existing code around it, the discontinuity
				6424	throws readers out of their rhythm when they go to read it. Try
				6425	to avoid this.</p>
				6426
				6427
				6428
				6429	<p>OK, enough writing about writing code; the code itself is much
				6430	more interesting. Have fun!</p>
				6431
				6432	<hr>
				6433
				6434	</div>
				6435	</div>
				6436	</body>
				6437	</html>