| <?xml version="1.0"?> |
| <?xml-stylesheet type="text/xsl" href="styleguide.xsl"?> |
| <GUIDE title="Google C++ Style Guide"> |
| |
| <p align="right"> |
| |
| Revision 3.245 |
| </p> |
| |
| |
| |
| <address> |
| Benjy Weinberger<br/> |
| Craig Silverstein<br/> |
| Gregory Eitzmann<br/> |
| Mark Mentovai<br/> |
| Tashana Landray |
| </address> |
| |
| <OVERVIEW> |
| <CATEGORY title="Important Note"> |
| <STYLEPOINT title="Displaying Hidden Details in this Guide"> |
| <SUMMARY> |
| This style guide contains many details that are initially |
| hidden from view. They are marked by the triangle icon, which you |
| see here on your left. Click it now. |
| You should see "Hooray" appear below. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Hooray! Now you know you can expand points to get more |
| details. Alternatively, there's an "expand all" at the |
| top of this document. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| <CATEGORY title="Background"> |
| <p> |
| C++ is the main development language |
| |
| used by many of Google's open-source |
| projects. |
| As every C++ programmer knows, the language has many powerful features, |
| but this power brings with it complexity, which in turn can make code |
| more bug-prone and harder to read and maintain. |
| </p> |
| <p> |
| The goal of this guide is to manage this complexity by describing |
| in detail the dos and don'ts of writing C++ |
| code. These rules exist to |
| keep |
| |
| the |
| code base manageable while still allowing coders to use C++ language |
| features productively. |
| </p> |
| <p> |
| <em>Style</em>, also known as readability, is what we call the |
| conventions that govern our C++ code. The term Style is a bit of a |
| misnomer, since these conventions cover far more than just source |
| file formatting. |
| </p> |
| <p> |
| One way in which we keep the code base manageable is by enforcing |
| <em>consistency</em>. |
| |
| It is very important that any |
| |
| programmer |
| be able to look at another's code and quickly understand it. |
| Maintaining a uniform style and following conventions means that we can |
| more easily use "pattern-matching" to infer what various symbols are |
| and what invariants are true about them. Creating common, required |
| idioms and patterns makes code much easier to understand. In some |
| cases there might be good arguments for changing certain style |
| rules, but we nonetheless keep things as they are in order to |
| preserve consistency. |
| </p> |
| <p> |
| Another issue this guide addresses is that of C++ feature bloat. |
| C++ is a huge language with many advanced features. In some cases |
| we constrain, or even ban, use of certain features. We do this to |
| keep code simple and to avoid the various common errors and |
| problems that these features can cause. This guide lists these |
| features and explains why their use is restricted. |
| </p> |
| <p> |
| |
| Open-source projects developed by Google |
| conform to the requirements in this guide. |
| </p> |
| |
| <p> |
| Note that this guide is not a C++ tutorial: we assume that the |
| reader is familiar with the language. |
| |
| </p> |
| |
| </CATEGORY> |
| </OVERVIEW> |
| |
| <CATEGORY title="Header Files"> |
| <p> |
| In general, every <code>.cc</code> file should have an associated |
| <code>.h</code> file. There are some common exceptions, such as |
| |
| unittests |
| and small <code>.cc</code> files containing just a <code>main()</code> |
| function. |
| </p> |
| <p> |
| Correct use of header files can make a huge difference to the |
| readability, size and performance of your code. |
| </p> |
| <p> |
| The following rules will guide you through the various pitfalls of |
| using header files. |
| </p> |
| |
| <STYLEPOINT title="The #define Guard"> |
| <SUMMARY> |
| All header files should have <code>#define</code> guards to |
| prevent multiple inclusion. The format of the symbol name |
| should be |
| <code><i><PROJECT></i>_<i><PATH></i>_<i><FILE></i>_H_</code>. |
| </SUMMARY> |
| <BODY> |
| |
| <p> |
| To guarantee uniqueness, they should be based on the full path |
| in a project's source tree. For example, the file |
| <code>foo/src/bar/baz.h</code> in project <code>foo</code> should |
| have the following guard: |
| </p> |
| <CODE_SNIPPET> |
| #ifndef FOO_BAR_BAZ_H_ |
| #define FOO_BAR_BAZ_H_ |
| |
| ... |
| |
| #endif // FOO_BAR_BAZ_H_ |
| </CODE_SNIPPET> |
| |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Forward Declarations"> |
| <SUMMARY> |
| You may forward declare ordinary classes in order to avoid |
| unnecessary <code>#include</code>s. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| A "forward declaration" is a declaration of a class, function, |
| or template without an associated definition. <code>#include</code> |
| lines can often be replaced with forward declarations of whatever |
| symbols are actually used by the client code. |
| </DEFINITION> |
| <PROS> |
| <ul> |
| <li>Unnecessary <code>#include</code>s force the compiler to open |
| more files and process more input.</li> |
| <li>They can also force your code to be recompiled more often, due |
| to changes in the header.</li> |
| </ul> |
| </PROS> |
| <CONS> |
| <ul> |
| <li>It can be difficult to determine the correct form of a |
| forward declaration in the presence of features like templates, |
| typedefs, default parameters, and using declarations.</li> |
| <li>It can be difficult to determine whether a forward declaration |
| or a full <code>#include</code> is needed for a given piece of code, |
| particularly when implicit conversion operations are involved. In |
| extreme cases, replacing an <code>#include</code> with a forward |
| declaration can silently change the meaning of code.</li> |
| <li>Forward declaring multiple symbols from a header can be more |
| verbose than simply <code>#include</code>ing the header.</li> |
| <li>Forward declarations of functions and templates can prevent |
| the header owners from making otherwise-compatible changes to |
| their APIs; for example, widening a parameter type, or adding |
| a template parameter with a default value.</li> |
| <li>Forward declaring symbols from namespace <code>std::</code> |
| usually yields undefined behavior.</li> |
| <li>Structuring code to enable forward declarations (e.g. |
| using pointer members instead of object members) can make the |
| code slower and more complex.</li> |
| <li>The practical efficiency benefits of forward declarations are |
| unproven.</li> |
| </ul> |
| </CONS> |
| <DECISION> |
| <ul> |
| <li>When using a function declared in a header file, always |
| <code>#include</code> that header.</li> |
| <li>When using a class template, prefer to <code>#include</code> its |
| header file.</li> |
| <li>When using an ordinary class, relying on a forward declaration |
| is OK, but be wary of situations where a forward declaration may |
| be insufficient or incorrect; when in doubt, just |
| <code>#include</code> the appropriate header.</li> |
| <li>Do not replace data members with pointers just to avoid an |
| <code>#include</code>.</li> |
| </ul> |
| Always <code>#include</code> the file that actually provides the |
| declarations/definitions you need; do not rely on the symbol being |
| brought in transitively via headers not directly included. One |
| exception is that <code>myfile.cc</code> may rely on |
| <code>#include</code>s and forward declarations from its corresponding |
| header file <code>myfile.h</code>. |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Inline Functions"> |
| <SUMMARY> |
| Define functions inline only when they are small, say, 10 lines |
| or less. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| You can declare functions in a way that allows the compiler to |
| expand them inline rather than calling them through the usual |
| function call mechanism. |
| </DEFINITION> |
| <PROS> |
| Inlining a function can generate more efficient object code, |
| as long as the inlined function is small. Feel free to inline |
| accessors and mutators, and other short, performance-critical |
| functions. |
| </PROS> |
| <CONS> |
| Overuse of inlining can actually make programs slower. |
| Depending on a function's size, inlining it can cause the code |
| size to increase or decrease. Inlining a very small accessor |
| function will usually decrease code size while inlining a very |
| large function can dramatically increase code size. On modern |
| processors smaller code usually runs faster due to better use |
| of the instruction cache. |
| </CONS> |
| <DECISION> |
| <p> |
| A decent rule of thumb is to not inline a function if it is |
| more than 10 lines long. Beware of destructors, which are |
| often longer than they appear because of implicit member- |
| and base-destructor calls! |
| </p> |
| <p> |
| Another useful rule of thumb: it's typically not cost |
| effective to inline functions with loops or switch |
| statements (unless, in the common case, the loop or switch |
| statement is never executed). |
| </p> |
| <p> |
| It is important to know that functions are not always |
| inlined even if they are declared as such; for example, |
| virtual and recursive functions are not normally inlined. |
| Usually recursive functions should not be inline. The main |
| reason for making a virtual function inline is to place its |
| definition in the class, either for convenience or to |
| document its behavior, e.g., for accessors and mutators. |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="The -inl.h Files"> |
| <SUMMARY> |
| You may use file names with a <code>-inl.h</code> suffix to define |
| complex inline functions when needed. |
| </SUMMARY> |
| <BODY> |
| <p> |
| The definition of an inline function needs to be in a header |
| file, so that the compiler has the definition available for |
| inlining at the call sites. However, implementation code |
| properly belongs in <code>.cc</code> files, and we do not like |
| to have much actual code in <code>.h</code> files unless there |
| is a readability or performance advantage. |
| </p> |
| <p> |
| If an inline function definition is short, with very little, |
| if any, logic in it, you should put the code in your |
| <code>.h</code> file. For example, accessors and mutators |
| should certainly be inside a class definition. More complex |
| inline functions may also be put in a <code>.h</code> file for |
| the convenience of the implementer and callers, though if this |
| makes the <code>.h</code> file too unwieldy you can instead |
| put that code in a separate <code>-inl.h</code> file. |
| This separates the implementation from the class definition, |
| while still allowing the implementation to be included where |
| necessary. |
| </p> |
| <p> |
| Another use of <code>-inl.h</code> files is for definitions of |
| function templates. This can be used to keep your template |
| definitions easy to read. |
| </p> |
| <p> |
| Do not forget that a <code>-inl.h</code> file requires a |
| <a href="#The__define_Guard"><code>#define</code> guard</a> just |
| like any other header file. |
| </p> |
| |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Function Parameter Ordering"> |
| <SUMMARY> |
| When defining a function, parameter order is: inputs, |
| then outputs. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Parameters to C/C++ functions are either input to the |
| function, output from the function, or both. Input parameters |
| are usually values or <code>const</code> references, while output |
| and input/output parameters will be non-<code>const</code> |
| pointers. When ordering function parameters, put all input-only |
| parameters before any output parameters. In particular, do not add |
| new parameters to the end of the function just because they are |
| new; place new input-only parameters before the output |
| parameters. |
| </p> |
| <p> |
| This is not a hard-and-fast rule. Parameters that are both |
| input and output (often classes/structs) muddy the waters, |
| and, as always, consistency with related functions may require |
| you to bend the rule. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Names and Order of Includes"> |
| <SUMMARY> |
| Use standard order for readability and to avoid hidden |
| dependencies: C library, C++ library, |
| |
| other libraries' <code>.h</code>, your |
| project's |
| <code>.h</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| |
| All of a project's header files should be |
| listed as descendants of the project's source directory |
| without use of UNIX directory shortcuts <code>.</code> (the current |
| directory) or <code>..</code> (the parent directory). For |
| example, |
| |
| <code>google-awesome-project/src/base/logging.h</code> |
| should be included as |
| </p> |
| <CODE_SNIPPET> |
| #include "base/logging.h" |
| </CODE_SNIPPET> |
| <p> |
| In <code><var>dir/foo</var>.cc</code> or <code><var>dir/foo_test</var>.cc</code>, |
| whose main purpose is to implement or test the stuff in |
| <code><var>dir2/foo2</var>.h</code>, order your includes as |
| follows: |
| </p> |
| <ol> |
| <li> <code><var>dir2/foo2</var>.h</code> (preferred location |
| — see details below).</li> |
| <li> C system files.</li> |
| <li> C++ system files.</li> |
| <li> Other libraries' <code>.h</code> files.</li> |
| <li> |
| Your project's |
| <code>.h</code> files.</li> |
| </ol> |
| <p> |
| With the preferred ordering, if <code><var>dir2/foo2</var>.h</code> |
| omits any necessary includes, the build of |
| <code><var>dir/foo</var>.cc</code> or |
| <code><var>dir/foo</var>_test.cc</code> will break. |
| Thus, this rule ensures that build breaks show up first |
| for the people working on these files, not for innocent people |
| in other packages. |
| </p> |
| <p> |
| <code><var>dir/foo</var>.cc</code> and |
| <code><var>dir2/foo2</var>.h</code> are often in the same |
| directory (e.g. <code>base/basictypes_test.cc</code> and |
| <code>base/basictypes.h</code>), but can be in different |
| directories too. |
| </p> |
| |
| <p> |
| Within each section the includes should be ordered alphabetically. |
| Note that older code might not conform to this rule and should be |
| fixed when convenient. |
| </p> |
| <p> |
| For example, the includes in |
| |
| <code>google-awesome-project/src/foo/internal/fooserver.cc</code> |
| might look like this: |
| </p> |
| <CODE_SNIPPET> |
| #include "foo/public/fooserver.h" // Preferred location. |
| |
| #include <sys/types.h> |
| #include <unistd.h> |
| #include <hash_map> |
| #include <vector> |
| |
| #include "base/basictypes.h" |
| #include "base/commandlineflags.h" |
| #include "foo/public/bar.h" |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="Scoping"> |
| <STYLEPOINT title="Namespaces"> |
| <SUMMARY> |
| Unnamed namespaces in <code>.cc</code> files are encouraged. With |
| named namespaces, choose the name based on the |
| |
| project, and possibly its path. |
| Do not use a <SYNTAX>using-directive</SYNTAX>. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| Namespaces subdivide the global scope into distinct, named |
| scopes, and so are useful for preventing name collisions in |
| the global scope. |
| </DEFINITION> |
| <PROS> |
| <p> |
| Namespaces provide a (hierarchical) axis of naming, in |
| addition to the (also hierarchical) name axis provided by |
| classes. |
| </p> |
| <p> |
| For example, if two different projects have a class |
| <code>Foo</code> in the global scope, these symbols may |
| collide at compile time or at runtime. If each project |
| places their code in a namespace, <code>project1::Foo</code> |
| and <code>project2::Foo</code> are now distinct symbols that |
| do not collide. |
| </p> |
| </PROS> |
| <CONS> |
| <p> |
| Namespaces can be confusing, because they provide an |
| additional (hierarchical) axis of naming, in addition to the |
| (also hierarchical) name axis provided by classes. |
| </p> |
| <p> |
| Use of unnamed namespaces in header files can easily cause |
| violations of the C++ One Definition Rule (ODR). |
| </p> |
| </CONS> |
| <DECISION> |
| <p> |
| Use namespaces according to the policy described below. |
| Terminate namespaces with comments as shown in the given examples. |
| </p> |
| |
| <SUBSECTION title="Unnamed Namespaces"> |
| <ul> |
| <li> Unnamed namespaces are allowed and even encouraged in |
| <code>.cc</code> files, to avoid runtime naming |
| conflicts: |
| <CODE_SNIPPET> |
| namespace { // This is in a .cc file. |
| |
| // The content of a namespace is not indented |
| enum { kUnused, kEOF, kError }; // Commonly used tokens. |
| bool AtEof() { return pos_ == kEOF; } // Uses our namespace's EOF. |
| |
| } // namespace |
| </CODE_SNIPPET> |
| |
| <p> |
| However, file-scope declarations that are |
| associated with a particular class may be declared |
| in that class as types, static data members or |
| static member functions rather than as members of |
| an unnamed namespace. |
| </p> |
| </li> |
| <li> Do not use unnamed namespaces in <code>.h</code> |
| files. |
| </li> |
| </ul> |
| </SUBSECTION> |
| |
| <SUBSECTION title="Named Namespaces"> |
| <p> |
| Named namespaces should be used as follows: |
| </p> |
| <ul> |
| <li> Namespaces wrap the entire source file after includes, |
| |
| <a href="http://google-gflags.googlecode.com/">gflags</a> |
| definitions/declarations, and forward declarations of classes |
| from other namespaces: |
| <CODE_SNIPPET> |
| // In the .h file |
| namespace mynamespace { |
| |
| // All declarations are within the namespace scope. |
| // Notice the lack of indentation. |
| class MyClass { |
| public: |
| ... |
| void Foo(); |
| }; |
| |
| } // namespace mynamespace |
| </CODE_SNIPPET> |
| <CODE_SNIPPET> |
| // In the .cc file |
| namespace mynamespace { |
| |
| // Definition of functions is within scope of the namespace. |
| void MyClass::Foo() { |
| ... |
| } |
| |
| } // namespace mynamespace |
| </CODE_SNIPPET> |
| <p> |
| The typical <code>.cc</code> file might have more |
| complex detail, including the need to reference classes |
| in other namespaces. |
| </p> |
| <CODE_SNIPPET> |
| #include "a.h" |
| |
| DEFINE_bool(someflag, false, "dummy flag"); |
| |
| class C; // Forward declaration of class C in the global namespace. |
| namespace a { class A; } // Forward declaration of a::A. |
| |
| namespace b { |
| |
| ...code for b... // Code goes against the left margin. |
| |
| } // namespace b |
| </CODE_SNIPPET> |
| </li> |
| |
| |
| |
| <li> Do not declare anything in namespace |
| <code>std</code>, not even forward declarations of |
| standard library classes. Declaring entities in |
| namespace <code>std</code> is undefined behavior, |
| i.e., not portable. To declare entities from the |
| standard library, include the appropriate header |
| file. |
| </li> |
| |
| <li> You may not use a <SYNTAX>using-directive</SYNTAX> to |
| make all names from a namespace available. |
| <BAD_CODE_SNIPPET> |
| // Forbidden -- This pollutes the namespace. |
| using namespace foo; |
| </BAD_CODE_SNIPPET> |
| </li> |
| |
| <li> You may use a <SYNTAX>using-declaration</SYNTAX> |
| anywhere in a <code>.cc</code> file, and in functions, |
| methods or classes in <code>.h</code> files. |
| <CODE_SNIPPET> |
| // OK in .cc files. |
| // Must be in a function, method or class in .h files. |
| using ::foo::bar; |
| </CODE_SNIPPET> |
| </li> |
| |
| <li> Namespace aliases are allowed anywhere in a |
| <code>.cc</code> file, anywhere inside the named |
| namespace that wraps an entire <code>.h</code> file, |
| and in functions and methods. |
| <CODE_SNIPPET> |
| // Shorten access to some commonly used names in .cc files. |
| namespace fbz = ::foo::bar::baz; |
| |
| // Shorten access to some commonly used names (in a .h file). |
| namespace librarian { |
| // The following alias is available to all files including |
| // this header (in namespace librarian): |
| // alias names should therefore be chosen consistently |
| // within a project. |
| namespace pd_s = ::pipeline_diagnostics::sidetable; |
| |
| inline void my_inline_function() { |
| // namespace alias local to a function (or method). |
| namespace fbz = ::foo::bar::baz; |
| ... |
| } |
| } // namespace librarian |
| </CODE_SNIPPET> |
| <p> |
| Note that an alias in a .h file is visible to everyone |
| #including that file, so public headers (those available |
| outside a project) and headers transitively #included by them, |
| should avoid defining aliases, as part of the general |
| goal of keeping public APIs as small as possible. |
| </p> |
| </li> |
| </ul> |
| </SUBSECTION> |
| |
| |
| |
| |
| |
| |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Nested Classes"> |
| <SUMMARY> |
| Although you may use public nested classes when they are part of |
| an interface, consider a <a HREF="#Namespaces">namespace</a> to |
| keep declarations out of the global scope. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| A class can define another class within it; this is also |
| called a <SYNTAX>member class</SYNTAX>. |
| <CODE_SNIPPET> |
| class Foo { |
| |
| private: |
| // Bar is a member class, nested within Foo. |
| class Bar { |
| ... |
| }; |
| |
| }; |
| </CODE_SNIPPET> |
| </DEFINITION> |
| <PROS> |
| This is useful when the nested (or member) class is only used |
| by the enclosing class; making it a member puts it in the |
| enclosing class scope rather than polluting the outer scope |
| with the class name. Nested classes can be forward declared |
| within the enclosing class and then defined in the |
| <code>.cc</code> file to avoid including the nested class |
| definition in the enclosing class declaration, since the |
| nested class definition is usually only relevant to the |
| implementation. |
| </PROS> |
| <CONS> |
| Nested classes can be forward-declared only within the |
| definition of the enclosing class. Thus, any header file |
| manipulating a <code>Foo::Bar*</code> pointer will have to |
| include the full class declaration for <code>Foo</code>. |
| </CONS> |
| <DECISION> |
| Do not make nested classes public unless they are actually |
| part of the interface, e.g., a class that holds a set of |
| options for some method. |
| |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Nonmember, Static Member, and Global Functions"> |
| <SUMMARY> |
| Prefer nonmember functions within a namespace or static member |
| functions to global functions; use completely global functions |
| rarely. |
| </SUMMARY> |
| <BODY> |
| <PROS> |
| Nonmember and static member functions can be useful in some |
| situations. Putting nonmember functions in a namespace avoids |
| polluting the global namespace. |
| </PROS> |
| <CONS> |
| Nonmember and static member functions may make more sense as |
| members of a new class, especially if they access external |
| resources or have significant dependencies. |
| </CONS> |
| <DECISION> |
| <p> |
| Sometimes it is useful, or even necessary, to define a |
| function not bound to a class instance. Such a function can |
| be either a static member or a nonmember function. |
| Nonmember functions should not depend on external variables, |
| and should nearly always exist in a namespace. Rather than |
| creating classes only to group static member functions which |
| do not share static data, use |
| <a href="#Namespaces">namespaces</a> instead. |
| </p> |
| <p> |
| Functions defined in the same compilation unit as production |
| classes may introduce unnecessary coupling and link-time |
| dependencies when directly called from other compilation |
| units; static member functions are particularly susceptible |
| to this. Consider extracting a new class, or placing the |
| functions in a namespace possibly in a separate library. |
| </p> |
| <p> |
| If you must define a nonmember function and it is only |
| needed in its <code>.cc</code> file, use an unnamed |
| <a HREF="#Namespaces">namespace</a> or <code>static</code> |
| linkage (eg <code>static int Foo() {...}</code>) to limit |
| its scope. |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Local Variables"> |
| <SUMMARY> |
| Place a function's variables in the narrowest scope possible, |
| and initialize variables in the declaration. |
| </SUMMARY> |
| <BODY> |
| <p> |
| C++ allows you to declare variables anywhere in a function. |
| We encourage you to declare them in as local a scope as |
| possible, and as close to the first use as possible. This |
| makes it easier for the reader to find the declaration and see |
| what type the variable is and what it was initialized to. In |
| particular, initialization should be used instead of |
| declaration and assignment, e.g. |
| </p> |
| <BAD_CODE_SNIPPET> |
| int i; |
| i = f(); // Bad -- initialization separate from declaration. |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| int j = g(); // Good -- declaration has initialization. |
| </CODE_SNIPPET> |
| <p> |
| Note that gcc implements <code>for (int i = 0; i |
| < 10; ++i)</code> correctly (the scope of <code>i</code> is |
| only the scope of the <code>for</code> loop), so you can then |
| reuse <code>i</code> in another <code>for</code> loop in the |
| same scope. It also correctly scopes declarations in |
| <code>if</code> and <code>while</code> statements, e.g. |
| </p> |
| <CODE_SNIPPET> |
| while (const char* p = strchr(str, '/')) str = p + 1; |
| </CODE_SNIPPET> |
| <p> |
| There is one caveat: if the variable is an object, its |
| constructor is invoked every time it enters scope and is |
| created, and its destructor is invoked every time it goes |
| out of scope. |
| </p> |
| <BAD_CODE_SNIPPET> |
| // Inefficient implementation: |
| for (int i = 0; i < 1000000; ++i) { |
| Foo f; // My ctor and dtor get called 1000000 times each. |
| f.DoSomething(i); |
| } |
| </BAD_CODE_SNIPPET> |
| <p> |
| It may be more efficient to declare such a variable used in a |
| loop outside that loop: |
| </p> |
| <CODE_SNIPPET> |
| Foo f; // My ctor and dtor get called once each. |
| for (int i = 0; i < 1000000; ++i) { |
| f.DoSomething(i); |
| } |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Static and Global Variables"> |
| <SUMMARY> |
| Static or global variables of class type are forbidden: they cause |
| hard-to-find bugs due to indeterminate order of construction and |
| destruction. |
| However, such variables are allowed if they are <code>constexpr</code>: |
| they have no dynamic initialization or destruction. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Objects with static storage duration, including global variables, |
| static variables, static class member variables, and function static |
| variables, must be Plain Old Data (POD): only ints, chars, floats, or |
| pointers, or arrays/structs of POD. |
| </p> |
| <p> |
| The order in which class constructors and initializers for |
| static variables are called is only partially specified in C++ and can |
| even change from build to build, which can cause bugs that are difficult |
| to find. Therefore in addition to banning globals of class type, we do |
| not allow static POD variables to be initialized with the result of a |
| function, unless that function (such as getenv(), or getpid()) does not |
| itself depend on any other globals. |
| </p> |
| <p> |
| Likewise, the order in which destructors are called is defined to be the |
| reverse of the order in which the constructors were called. Since |
| constructor order is indeterminate, so is destructor order. |
| For example, at program-end time a static variable might have |
| been destroyed, but code still running -- perhaps in another thread -- |
| tries to access it and fails. Or the destructor for a static 'string' |
| variable might be run prior to the destructor for another variable that |
| contains a reference to that string. |
| </p> |
| <p> |
| As a result we only allow static variables to contain POD data. This |
| rule completely disallows <code>vector</code> (use C arrays instead), or |
| <code>string</code> (use <code>const char []</code>). |
| </p> |
| |
| <p> |
| If you need a static or global variable of a class type, consider |
| initializing a pointer (which will never be freed), from either your |
| main() function or from pthread_once(). Note that this must be a raw |
| pointer, not a "smart" pointer, since the smart pointer's destructor |
| will have the order-of-destructor issue that we are trying to avoid. |
| </p> |
| |
| |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="Classes"> |
| Classes are the fundamental unit of code in C++. Naturally, we use |
| them extensively. This section lists the main dos and don'ts you |
| should follow when writing a class. |
| |
| <STYLEPOINT title="Doing Work in Constructors"> |
| <SUMMARY> |
| Avoid doing complex initialization in constructors (in particular, |
| initialization that can fail or that requires virtual method calls). |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| It is possible to perform initialization in the body of the |
| constructor. |
| </DEFINITION> |
| <PROS> |
| Convenience in typing. No need to worry about whether the |
| class has been initialized or not. |
| </PROS> |
| <CONS> |
| The problems with doing work in constructors are: |
| <ul> |
| <li> There is no easy way for constructors to signal errors, |
| short of using exceptions (which are |
| <a HREF="#Exceptions">forbidden</a>). |
| </li> |
| <li> If the work fails, we now have an object whose |
| initialization code failed, so it may be an |
| indeterminate state. |
| </li> |
| <li> If the work calls virtual functions, these calls will |
| not get dispatched to the subclass implementations. |
| Future modification to your class can quietly introduce |
| this problem even if your class is not currently |
| subclassed, causing much confusion. |
| </li> |
| <li> If someone creates a global variable of this type |
| (which is against the rules, but still), the |
| constructor code will be called before |
| <code>main()</code>, possibly breaking some implicit |
| assumptions in the constructor code. For instance, |
| |
| <a href="http://google-gflags.googlecode.com/">gflags</a> |
| will not yet have been initialized. |
| </li> |
| </ul> |
| </CONS> |
| <DECISION> |
| Constructors should never call virtual functions or attempt to raise |
| non-fatal failures. If your object requires non-trivial |
| initialization, consider using a factory function or <code>Init()</code> method. |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Default Constructors"> |
| <SUMMARY> |
| You must define a default constructor if your class defines |
| member variables and has no other constructors. Otherwise the |
| compiler will do it for you, badly. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| The default constructor is called when we <code>new</code> a |
| class object with no arguments. It is always called when |
| calling <code>new[]</code> (for arrays). |
| </DEFINITION> |
| <PROS> |
| Initializing structures by default, to hold "impossible" |
| values, makes debugging much easier. |
| </PROS> |
| <CONS> |
| Extra work for you, the code writer. |
| </CONS> |
| <DECISION> |
| <p> |
| If your class defines member variables and has no other |
| constructors you must define a default constructor (one that |
| takes no arguments). It should preferably initialize the |
| object in such a way that its internal state is consistent |
| and valid. |
| </p> |
| <p> |
| The reason for this is that if you have no other |
| constructors and do not define a default constructor, the |
| compiler will generate one for you. This compiler |
| generated constructor may not initialize your object |
| sensibly. |
| </p> |
| <p> |
| If your class inherits from an existing class but you add no |
| new member variables, you are not required to have a default |
| constructor. |
| |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Explicit Constructors"> |
| <SUMMARY> |
| Use the C++ keyword <code>explicit</code> for constructors with |
| one argument. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| Normally, if a constructor takes one argument, it can be used |
| as a conversion. For instance, if you define |
| <code>Foo::Foo(string name)</code> and then pass a string to a |
| function that expects a <code>Foo</code>, the constructor will |
| be called to convert the string into a <code>Foo</code> and |
| will pass the <code>Foo</code> to your function for you. This |
| can be convenient but is also a source of trouble when things |
| get converted and new objects created without you meaning them |
| to. Declaring a constructor <code>explicit</code> prevents it |
| from being invoked implicitly as a conversion. |
| </DEFINITION> |
| <PROS> |
| Avoids undesirable conversions. |
| </PROS> |
| <CONS> |
| None. |
| </CONS> |
| <DECISION> |
| <p> |
| We require all single argument constructors to be |
| explicit. Always put <code>explicit</code> in front of |
| one-argument constructors in the class definition: |
| <code>explicit Foo(string name);</code> |
| </p> |
| <p> |
| The exception is copy constructors, which, in the rare |
| cases when we allow them, should probably not be |
| <code>explicit</code>. |
| |
| Classes that are intended to be |
| transparent wrappers around other classes are also |
| exceptions. |
| Such exceptions should be clearly marked with comments. |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Copy Constructors"> |
| <SUMMARY> |
| Provide a copy constructor and assignment operator only when necessary. |
| Otherwise, disable them with <code>DISALLOW_COPY_AND_ASSIGN</code>. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| The copy constructor and assignment operator are used to create copies |
| of objects. The copy constructor is implicitly invoked by the |
| compiler in some situations, e.g. passing objects by value. |
| </DEFINITION> |
| <PROS> |
| Copy constructors make it easy to copy objects. STL |
| containers require that all contents be copyable and |
| assignable. Copy constructors can be more efficient than |
| <code>CopyFrom()</code>-style workarounds because they combine |
| construction with copying, the compiler can elide them in some |
| contexts, and they make it easier to avoid heap allocation. |
| </PROS> |
| <CONS> |
| Implicit copying of objects in C++ is a rich source of bugs |
| and of performance problems. It also reduces readability, as |
| it becomes hard to track which objects are being passed around |
| by value as opposed to by reference, and therefore where |
| changes to an object are reflected. |
| </CONS> |
| <DECISION> |
| <p> |
| Few classes need to be copyable. Most should have neither a |
| copy constructor nor an assignment operator. In many situations, |
| a pointer or reference will work just as well as a copied value, |
| with better performance. For example, you can pass function |
| parameters by reference or pointer instead of by value, and you can |
| store pointers rather than objects in an STL container. |
| </p> |
| <p> |
| If your class needs to be copyable, prefer providing a copy method, |
| such as <code>CopyFrom()</code> or <code>Clone()</code>, rather than |
| a copy constructor, because such methods cannot be invoked |
| implicitly. If a copy method is insufficient in your situation |
| (e.g. for performance reasons, or because your class needs to be |
| stored by value in an STL container), provide both a copy |
| constructor and assignment operator. |
| </p> |
| <p> |
| If your class does not need a copy constructor or assignment |
| operator, you must explicitly disable them. |
| |
| |
| To do so, add dummy declarations for the copy constructor and |
| assignment operator in the <code>private:</code> section of your |
| class, but do not provide any corresponding definition (so that |
| any attempt to use them results in a link error). |
| </p> |
| <p> |
| For convenience, a <code>DISALLOW_COPY_AND_ASSIGN</code> macro |
| can be used: |
| </p> |
| <CODE_SNIPPET> |
| // A macro to disallow the copy constructor and operator= functions |
| // This should be used in the private: declarations for a class |
| #define DISALLOW_COPY_AND_ASSIGN(TypeName) \ |
| TypeName(const TypeName&); \ |
| void operator=(const TypeName&) |
| </CODE_SNIPPET> |
| <p> |
| Then, in <code>class Foo</code>: |
| </p> |
| <CODE_SNIPPET> |
| class Foo { |
| public: |
| Foo(int f); |
| ~Foo(); |
| |
| private: |
| DISALLOW_COPY_AND_ASSIGN(Foo); |
| }; |
| </CODE_SNIPPET> |
| <p> |
| </p> |
| |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Structs vs. Classes"> |
| <SUMMARY> |
| Use a <code>struct</code> only for passive objects that carry data; |
| everything else is a <code>class</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| The <code>struct</code> and <code>class</code> keywords behave |
| almost identically in C++. We add our own semantic meanings |
| to each keyword, so you should use the appropriate keyword for |
| the data-type you're defining. |
| </p> |
| <p> |
| <code>structs</code> should be used for passive objects that carry |
| data, and may have associated constants, but lack any functionality |
| other than access/setting the data members. The |
| accessing/setting of fields is done by directly accessing the |
| fields rather than through method invocations. Methods should |
| not provide behavior but should only be used to set up the |
| data members, e.g., constructor, destructor, |
| <code>Initialize()</code>, <code>Reset()</code>, |
| <code>Validate()</code>. |
| </p> |
| <p> |
| If more functionality is required, a <code>class</code> is more |
| appropriate. If in doubt, make it a <code>class</code>. |
| </p> |
| <p> |
| For consistency with STL, you can use <code>struct</code> |
| instead of <code>class</code> for functors and traits. |
| </p> |
| <p> |
| Note that member variables in structs and classes have |
| <a HREF="#Variable_Names">different naming rules</a>. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Inheritance"> |
| <SUMMARY> |
| Composition is often more appropriate than inheritance. When |
| using inheritance, make it <code>public</code>. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| When a sub-class inherits from a base class, it includes the |
| definitions of all the data and operations that the parent |
| base class defines. In practice, inheritance is used in two |
| major ways in C++: implementation inheritance, in which |
| actual code is inherited by the child, and <A HREF="#Interfaces">interface inheritance</A>, in which only |
| method names are inherited. |
| </DEFINITION> |
| <PROS> |
| Implementation inheritance reduces code size by re-using the |
| base class code as it specializes an existing type. Because |
| inheritance is a compile-time declaration, you and the |
| compiler can understand the operation and detect errors. |
| Interface inheritance can be used to programmatically enforce |
| that a class expose a particular API. Again, the compiler |
| can detect errors, in this case, when a class does not define |
| a necessary method of the API. |
| </PROS> |
| <CONS> |
| For implementation inheritance, because the code implementing |
| a sub-class is spread between the base and the sub-class, it |
| can be more difficult to understand an implementation. The |
| sub-class cannot override functions that are not virtual, so |
| the sub-class cannot change implementation. The base class |
| may also define some data members, so that specifies physical |
| layout of the base class. |
| </CONS> |
| <DECISION> |
| <p> |
| All inheritance should be <code>public</code>. If you want to |
| do private inheritance, you should be including an instance of |
| the base class as a member instead. |
| </p> |
| <p> |
| Do not overuse implementation inheritance. Composition is |
| often more appropriate. Try to restrict use of inheritance |
| to the "is-a" case: <code>Bar</code> subclasses |
| <code>Foo</code> if it can reasonably be said that |
| <code>Bar</code> "is a kind of" <code>Foo</code>. |
| </p> |
| <p> |
| Make your destructor <code>virtual</code> if necessary. If |
| your class has virtual methods, its destructor |
| |
| should be virtual. |
| </p> |
| <p> |
| Limit the use of <code>protected</code> to those member |
| functions that might need to be accessed from subclasses. |
| Note that <a href="#Access_Control">data members should |
| be private</a>. |
| </p> |
| <p> |
| When redefining an inherited virtual function, explicitly |
| declare it <code>virtual</code> in the declaration of the |
| derived class. Rationale: If <code>virtual</code> is |
| omitted, the reader has to check all ancestors of the |
| class in question to determine if the function is virtual |
| or not. |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Multiple Inheritance"> |
| <SUMMARY> |
| Only very rarely is multiple implementation inheritance actually |
| useful. We allow multiple inheritance only when at most one of |
| the base classes has an implementation; all other base classes |
| must be <A HREF="#Interfaces">pure interface</A> classes tagged |
| with the <code>Interface</code> suffix. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| Multiple inheritance allows a sub-class to have more than one |
| base class. We distinguish between base classes that are |
| <em>pure interfaces</em> and those that have an |
| <em>implementation</em>. |
| </DEFINITION> |
| <PROS> |
| Multiple implementation inheritance may let you re-use even more code |
| than single inheritance (see <a HREF="#Inheritance">Inheritance</a>). |
| </PROS> |
| <CONS> |
| Only very rarely is multiple <em>implementation</em> |
| inheritance actually useful. When multiple implementation |
| inheritance seems like the solution, you can usually find a |
| different, more explicit, and cleaner solution. |
| </CONS> |
| <DECISION> |
| Multiple inheritance is allowed only when all superclasses, with the |
| possible exception of the first one, are <A HREF="#Interfaces">pure |
| interfaces</A>. In order to ensure that they remain pure interfaces, |
| they must end with the <code>Interface</code> suffix. |
| <SUBSECTION title="Note:"> |
| There is an <a HREF="#Windows_Code">exception</a> to this |
| rule on Windows. |
| </SUBSECTION> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Interfaces"> |
| <SUMMARY> |
| Classes that satisfy certain conditions are allowed, but not required, to |
| end with an <code>Interface</code> suffix. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| <p> |
| A class is a pure interface if it meets the following requirements: |
| </p> |
| <ul> |
| <li> It has only public pure virtual ("<code>= 0</code>") methods |
| and static methods (but see below for destructor). |
| </li> |
| <li> It may not have non-static data members. |
| </li> |
| <li> It need not have any constructors defined. If a constructor is |
| provided, it must take no arguments and it must be protected. |
| </li> |
| <li> If it is a subclass, it may only be derived from classes |
| that satisfy these conditions and are tagged with the |
| <code>Interface</code> suffix. |
| </li> |
| </ul> |
| <p> |
| An interface class can never be directly instantiated |
| because of the pure virtual method(s) it declares. To make |
| sure all implementations of the interface can be destroyed |
| correctly, the interface must also declare a virtual destructor (in |
| an exception to the first rule, this should not be pure). See |
| Stroustrup, <cite>The C++ Programming Language</cite>, 3rd |
| edition, section 12.4 for details. |
| </p> |
| </DEFINITION> |
| <PROS> |
| Tagging a class with the <code>Interface</code> suffix lets |
| others know that they must not add implemented methods or non |
| static data members. This is particularly important in the case of |
| <A HREF="#Multiple_Inheritance">multiple inheritance</A>. |
| Additionally, the interface concept is already well-understood by |
| Java programmers. |
| </PROS> |
| <CONS> |
| The <code>Interface</code> suffix lengthens the class name, which |
| can make it harder to read and understand. Also, the interface |
| property may be considered an implementation detail that shouldn't |
| be exposed to clients. |
| </CONS> |
| <DECISION> |
| A class may end with <code>Interface</code> only if it meets the |
| above requirements. We do not require the converse, however: |
| classes that meet the above requirements are not required to end |
| with <code>Interface</code>. |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Operator Overloading"> |
| <SUMMARY> |
| Do not overload operators except in rare, special circumstances. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| A class can define that operators such as <code>+</code> and |
| <code>/</code> operate on the class as if it were a built-in |
| type. |
| </DEFINITION> |
| <PROS> |
| Can make code appear more intuitive because a class will |
| behave in the same way as built-in types (such as |
| <code>int</code>). Overloaded operators are more playful |
| names for functions that are less-colorfully named, such as |
| <code>Equals()</code> or <code>Add()</code>. For some |
| template functions to work correctly, you may need to define |
| operators. |
| </PROS> |
| <CONS> |
| While operator overloading can make code more intuitive, it |
| has several drawbacks: |
| <ul> |
| <li> It can fool our intuition into thinking that expensive |
| operations are cheap, built-in operations. |
| </li> |
| <li> It is much harder to find the call sites for overloaded |
| operators. Searching for <code>Equals()</code> is much |
| easier than searching for relevant invocations of |
| <code>==</code>. |
| </li> |
| <li> Some operators work on pointers too, making it easy to |
| introduce bugs. <code>Foo + 4</code> may do one thing, |
| while <code>&Foo + 4</code> does something totally |
| different. The compiler does not complain for either of |
| these, making this very hard to debug. |
| </li> |
| </ul> |
| Overloading also has surprising ramifications. For instance, |
| if a class overloads unary <code>operator&</code>, it |
| cannot safely be forward-declared. |
| </CONS> |
| <DECISION> |
| <p> |
| In general, do not overload operators. The assignment operator |
| (<code>operator=</code>), in particular, is insidious and |
| should be avoided. You can define functions like |
| <code>Equals()</code> and <code>CopyFrom()</code> if you |
| need them. Likewise, avoid the dangerous |
| unary <code>operator&</code> at all costs, if there's |
| any possibility the class might be forward-declared. |
| </p> |
| <p> |
| However, there may be rare cases where you need to overload |
| an operator to interoperate with templates or "standard" C++ |
| classes (such as <code>operator<<(ostream&, const |
| T&)</code> for logging). These are acceptable if fully |
| justified, but you should try to avoid these whenever |
| possible. In particular, do not overload <code>operator==</code> |
| or <code>operator<</code> just so that your class can be |
| used as a key in an STL container; instead, you should |
| create equality and comparison functor types when declaring |
| the container. |
| </p> |
| <p> |
| Some of the STL algorithms do require you to overload |
| <code>operator==</code>, and you may do so in these cases, |
| provided you document why. |
| </p> |
| <p> |
| See also <a HREF="#Copy_Constructors">Copy Constructors</a> |
| and <a HREF="#Function_Overloading">Function |
| Overloading</a>. |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Access Control"> |
| <SUMMARY> |
| Make data members <code>private</code>, and provide |
| access to them through accessor functions as needed (for |
| technical reasons, we allow data members of a test fixture class |
| to be <code>protected</code> when using |
| |
| <A HREF="http://code.google.com/p/googletest/"> |
| Google Test</A>). Typically a variable would be |
| called <code>foo_</code> and the accessor function |
| <code>foo()</code>. You may also want a mutator function |
| <code>set_foo()</code>. |
| Exception: <code>static const</code> data members (typically |
| called <code>kFoo</code>) need not be <code>private</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| The definitions of accessors are usually inlined in the header |
| file. |
| </p> |
| <p> |
| See also <a HREF="#Inheritance">Inheritance</a> and <a HREF="#Function_Names">Function Names</a>. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Declaration Order"> |
| <SUMMARY> |
| Use the specified order of declarations within a class: |
| <code>public:</code> before <code>private:</code>, methods |
| before data members (variables), etc. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Your class definition should start with its <code>public:</code> |
| section, followed by its <code>protected:</code> section and |
| then its <code>private:</code> section. If any of these sections |
| are empty, omit them. |
| </p> |
| <p> |
| Within each section, the declarations generally should be in |
| the following order: |
| </p> |
| <ul> |
| <li> Typedefs and Enums</li> |
| <li> Constants (<code>static const</code> data members)</li> |
| <li> Constructors</li> |
| <li> Destructor</li> |
| <li> Methods, including static methods</li> |
| <li> Data Members (except <code>static const</code> data members)</li> |
| </ul> |
| <p> |
| Friend declarations should always be in the private section, and |
| the <code>DISALLOW_COPY_AND_ASSIGN</code> macro invocation |
| should be at the end of the <code>private:</code> section. It |
| should be the last thing in the class. See <a HREF="#Copy_Constructors">Copy Constructors</a>. |
| </p> |
| <p> |
| Method definitions in the corresponding <code>.cc</code> file |
| should be the same as the declaration order, as much as possible. |
| </p> |
| <p> |
| Do not put large method definitions inline in the class |
| definition. Usually, only trivial or performance-critical, |
| and very short, methods may be defined inline. See <a HREF="#Inline_Functions">Inline Functions</a> for more |
| details. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Write Short Functions"> |
| <SUMMARY> |
| Prefer small and focused functions. |
| </SUMMARY> |
| <BODY> |
| <p> |
| We recognize that long functions are sometimes appropriate, so |
| no hard limit is placed on functions length. If a function |
| exceeds about 40 lines, think about whether it can be broken |
| up without harming the structure of the program. |
| </p> |
| <p> |
| Even if your long function works perfectly now, someone |
| modifying it in a few months may add new behavior. This could |
| result in bugs that are hard to find. Keeping your functions |
| short and simple makes it easier for other people to read and |
| modify your code. |
| </p> |
| <p> |
| You could find long and complicated functions when working |
| with |
| |
| some |
| code. Do not be intimidated by modifying existing |
| code: if working with such a function proves to be difficult, |
| you find that errors are hard to debug, or you want to use a |
| piece of it in several different contexts, consider breaking |
| up the function into smaller and more manageable pieces. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="Google-Specific Magic"> |
| |
| <p> |
| There are various tricks and utilities that we use to make C++ |
| code more robust, and various ways we use C++ that may differ from |
| what you see elsewhere. |
| </p> |
| |
| |
| |
| <STYLEPOINT title="Smart Pointers"> |
| |
| <SUMMARY> |
| If you actually need pointer semantics, <code>scoped_ptr</code> |
| is great. You should only use <code>std::tr1::shared_ptr</code> |
| with a non-const referent when it is truly necessary to share ownership |
| of an object (e.g. inside an STL container). You should never use |
| <code>auto_ptr</code>. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| "Smart" pointers are objects that act like pointers, but automate |
| management of the underlying memory. |
| </DEFINITION> |
| <PROS> |
| Smart pointers are extremely useful for preventing memory leaks, and |
| are essential for writing exception-safe code. They also formalize |
| and document the ownership of dynamically allocated memory. |
| </PROS> |
| <CONS> |
| We prefer designs in which objects have single, fixed owners. Smart |
| pointers which enable sharing or transfer of ownership can act as a |
| tempting alternative to a careful design of ownership semantics, |
| leading to confusing code and even bugs in which memory is never |
| deleted. The semantics of smart pointers (especially |
| <code>auto_ptr</code>) can be nonobvious and confusing. The |
| exception-safety benefits of smart pointers are not decisive, since |
| we do not allow exceptions. |
| </CONS> |
| <DECISION> |
| <dl> |
| <dt><code>scoped_ptr</code></dt> |
| <dd>Straightforward and risk-free. Use wherever appropriate.</dd> |
| <dt><code>auto_ptr</code></dt> |
| <dd>Confusing and bug-prone ownership-transfer semantics. Do not use. |
| </dd> |
| <dt><code>shared_ptr</code></dt> |
| <dd> |
| Safe with const referents (i.e. <code>shared_ptr<const |
| T></code>). Reference-counted pointers with non-const referents |
| can occasionally be the best design, but try to rewrite with single |
| owners where possible. |
| </dd> |
| </dl> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="cpplint"> |
| <SUMMARY> |
| Use |
| <code>cpplint.py</code> |
| to detect style errors. |
| </SUMMARY> |
| <BODY> |
| <p> |
| <code>cpplint.py</code> |
| is a tool that reads a source file and |
| identifies many style errors. It is not perfect, and has both false |
| positives and false negatives, but it is still a valuable tool. False |
| positives can be ignored by putting <code>// NOLINT</code> at |
| the end of the line. |
| </p> |
| |
| <p> |
| Some projects have instructions on how to run <code>cpplint.py</code> |
| from their project tools. If the project you are contributing to does |
| not, you can download <A HREF="http://google-styleguide.googlecode.com/svn/trunk/cpplint/cpplint.py"><code>cpplint.py</code></A> separately. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| |
| </CATEGORY> |
| |
| <CATEGORY title="Other C++ Features"> |
| <STYLEPOINT title="Reference Arguments"> |
| <SUMMARY> |
| All parameters passed by reference must be labeled |
| <code>const</code>. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| In C, if a function needs to modify a variable, the |
| parameter must use a pointer, eg <code>int foo(int |
| *pval)</code>. In C++, the function can alternatively |
| declare a reference parameter: <code>int foo(int |
| &val)</code>. |
| </DEFINITION> |
| <PROS> |
| Defining a parameter as reference avoids ugly code like |
| <code>(*pval)++</code>. Necessary for some applications like |
| copy constructors. Makes it clear, unlike with pointers, that |
| a null pointer is not a possible value. |
| </PROS> |
| <CONS> |
| References can be confusing, as they have value syntax but |
| pointer semantics. |
| </CONS> |
| <DECISION> |
| <p> |
| Within function parameter lists all references must be |
| <code>const</code>: |
| </p> |
| <CODE_SNIPPET> |
| void Foo(const string &in, string *out); |
| </CODE_SNIPPET> |
| <p> |
| In fact it is a very strong convention in Google code that input |
| arguments are values or <code>const</code> references while |
| output arguments are pointers. Input parameters may be |
| <code>const</code> pointers, but we never allow |
| non-<code>const</code> reference parameters |
| except when required by convention, e.g., <code>swap()</code>. |
| </p> |
| <p> |
| |
| However, there are some instances where using <code>const T*</code> |
| is preferable to <code>const T&</code> for input parameters. For |
| example: |
| <ul> |
| <li>You want to pass in a null pointer.</li> |
| <li>The function saves a pointer or reference to the input.</li> |
| </ul> |
| |
| |
| Remember that most of the time input parameters are going to be |
| specified as <code>const T&</code>. Using <code>const T*</code> |
| instead communicates to the reader that the input is somehow treated |
| differently. So if you choose <code>const T*</code> rather than |
| <code>const T&</code>, do so for a concrete reason; otherwise it |
| will likely confuse readers by making them look for an explanation |
| that doesn't exist. |
| |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Function Overloading"> |
| <SUMMARY> |
| Use overloaded functions (including constructors) only if a |
| reader looking at a call site can get a good idea of what is |
| happening without having to first figure out exactly which |
| overload is being called. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| <p> |
| You may write a function that takes a |
| <code>const string&</code> and overload it with another that |
| takes <code>const char*</code>. |
| </p> |
| <CODE_SNIPPET> |
| class MyClass { |
| public: |
| void Analyze(const string &text); |
| void Analyze(const char *text, size_t textlen); |
| }; |
| </CODE_SNIPPET> |
| </DEFINITION> |
| <PROS> |
| Overloading can make code more intuitive by allowing an |
| identically-named function to take different arguments. It |
| may be necessary for templatized code, and it can be |
| convenient for Visitors. |
| </PROS> |
| <CONS> |
| If a function is overloaded by the argument types alone, a |
| reader may have to understand C++'s complex matching rules in |
| order to tell what's going on. Also many people are confused |
| by the semantics of inheritance if a derived class overrides |
| only some of the variants of a function. |
| </CONS> |
| <DECISION> |
| If you want to overload a function, consider qualifying the |
| name with some information about the arguments, e.g., |
| <code>AppendString()</code>, <code>AppendInt()</code> rather |
| than just <code>Append()</code>. |
| |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Default Arguments"> |
| <SUMMARY> |
| We do not allow default function parameters, except in limited |
| situations as explained below. Simulate them with function |
| overloading instead, if appropriate. |
| </SUMMARY> |
| <BODY> |
| <PROS> |
| Often you have a function that uses default values, but |
| occasionally you want to override the defaults. Default |
| parameters allow an easy way to do this without having to |
| define many functions for the rare exceptions. Compared to |
| overloading the function, default arguments have a cleaner |
| syntax, with less boilerplate and a clearer distinction |
| between 'required' and 'optional' arguments. |
| </PROS> |
| <CONS> |
| Function pointers are confusing in the presence of default |
| arguments, since the function signature often doesn't match |
| the call signature. Adding a default argument to an existing |
| function changes its type, which can cause problems with code |
| taking its address. Adding function overloads avoids these |
| problems. In addition, default parameters may result in |
| bulkier code since they are replicated at every call-site -- |
| as opposed to overloaded functions, where "the default" |
| appears only in the function definition. |
| </CONS> |
| <DECISION> |
| <p> |
| While the cons above are not that onerous, they still |
| outweigh the (small) benefits of default arguments over |
| function overloading. So except as described below, we |
| require all arguments to be explicitly specified. |
| </p> |
| <p> |
| One specific exception is when the function is a static |
| function (or in an unnamed namespace) in a .cc file. In |
| this case, the cons don't apply since the function's use is |
| so localized. |
| </p> |
| <p> |
| Another specific exception is when default arguments are |
| used to simulate variable-length argument lists. |
| </p> |
| <CODE_SNIPPET> |
| // Support up to 4 params by using a default empty AlphaNum. |
| string StrCat(const AlphaNum &a, |
| const AlphaNum &b = gEmptyAlphaNum, |
| const AlphaNum &c = gEmptyAlphaNum, |
| const AlphaNum &d = gEmptyAlphaNum); |
| </CODE_SNIPPET> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Variable-Length Arrays and alloca()"> |
| <SUMMARY> |
| We do not allow variable-length arrays or <code>alloca()</code>. |
| </SUMMARY> |
| <BODY> |
| <PROS> |
| Variable-length arrays have natural-looking syntax. Both |
| variable-length arrays and <code>alloca()</code> are very |
| efficient. |
| </PROS> |
| <CONS> |
| Variable-length arrays and alloca are not part of Standard |
| C++. More importantly, they allocate a data-dependent amount |
| of stack space that can trigger difficult-to-find memory |
| overwriting bugs: "It ran fine on my machine, but dies |
| mysteriously in production". |
| </CONS> |
| |
| <DECISION> |
| Use a safe allocator instead, such as |
| <code>scoped_ptr</code>/<code>scoped_array</code>. |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Friends"> |
| <SUMMARY> |
| We allow use of <code>friend</code> classes and functions, |
| within reason. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Friends should usually be defined in the same file so that the |
| reader does not have to look in another file to find uses of |
| the private members of a class. A common use of |
| <code>friend</code> is to have a <code>FooBuilder</code> class |
| be a friend of <code>Foo</code> so that it can construct the |
| inner state of <code>Foo</code> correctly, without exposing |
| this state to the world. In some cases it may be useful to |
| make a unittest class a friend of the class it tests. |
| </p> |
| <p> |
| Friends extend, but do not break, the encapsulation |
| boundary of a class. In some cases this is better than making |
| a member public when you want to give only one other class |
| access to it. However, most classes should interact with |
| other classes solely through their public members. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Exceptions"> |
| <SUMMARY> |
| We do not use C++ exceptions. |
| </SUMMARY> |
| <BODY> |
| <PROS> |
| <ul> |
| <li>Exceptions allow higher levels of an application to |
| decide how to handle "can't happen" failures in deeply |
| nested functions, without the obscuring and error-prone |
| bookkeeping of error codes.</li> |
| |
| |
| |
| <li>Exceptions are used by most other modern |
| languages. Using them in C++ would make it more consistent with |
| Python, Java, and the C++ that others are familiar with.</li> |
| |
| <li>Some third-party C++ libraries use exceptions, and turning |
| them off internally makes it harder to integrate with those |
| libraries.</li> |
| |
| <li>Exceptions are the only way for a constructor to fail. |
| We can simulate this with a factory function or an |
| <code>Init()</code> method, but these require heap |
| allocation or a new "invalid" state, respectively.</li> |
| |
| <li>Exceptions are really handy in testing frameworks.</li> |
| </ul> |
| </PROS> |
| <CONS> |
| <ul> |
| <li>When you add a <code>throw</code> statement to an existing |
| function, you must examine all of its transitive callers. Either |
| they must make at least the basic exception safety guarantee, or |
| they must never catch the exception and be happy with the |
| program terminating as a result. For instance, if |
| <code>f()</code> calls <code>g()</code> calls |
| <code>h()</code>, and <code>h</code> throws an exception |
| that <code>f</code> catches, <code>g</code> has to be |
| careful or it may not clean up properly.</li> |
| |
| <li>More generally, exceptions make the control flow of |
| programs difficult to evaluate by looking at code: functions |
| may return in places you don't expect. This causes |
| maintainability and debugging difficulties. You can minimize |
| this cost via some rules on how and where exceptions can be |
| used, but at the cost of more that a developer needs to know |
| and understand.</li> |
| |
| <li>Exception safety requires both RAII and different coding |
| practices. Lots of supporting machinery is needed to make |
| writing correct exception-safe code easy. Further, to avoid |
| requiring readers to understand the entire call graph, |
| exception-safe code must isolate logic that writes to |
| persistent state into a "commit" phase. This will have both |
| benefits and costs (perhaps where you're forced to obfuscate |
| code to isolate the commit). Allowing exceptions would force |
| us to always pay those costs even when they're not worth |
| it.</li> |
| |
| <li>Turning on exceptions adds data to each binary produced, |
| increasing compile time (probably slightly) and possibly |
| increasing address space pressure. |
| </li> |
| |
| <li>The availability of exceptions may encourage developers |
| to throw them when they are not appropriate or recover from |
| them when it's not safe to do so. For example, invalid user |
| input should not cause exceptions to be thrown. We would |
| need to make the style guide even longer to document these |
| restrictions!</li> |
| </ul> |
| </CONS> |
| <DECISION> |
| <p> |
| On their face, the benefits of using exceptions outweigh the |
| costs, especially in new projects. However, for existing code, |
| the introduction of exceptions has implications on all dependent |
| code. If exceptions can be propagated beyond a new project, it |
| also becomes problematic to integrate the new project into |
| existing exception-free code. Because most existing C++ code at |
| Google is not prepared to deal with exceptions, it is |
| comparatively difficult to adopt new code that generates |
| exceptions. |
| </p> |
| <p> |
| Given that Google's existing code is not exception-tolerant, the |
| costs of using exceptions are somewhat greater than the costs in |
| a new project. The conversion process would be slow and |
| error-prone. We don't believe that the available alternatives to |
| exceptions, such as error codes and assertions, introduce a |
| significant burden. |
| |
| </p> |
| <p> |
| Our advice against using exceptions is not predicated on |
| philosophical or moral grounds, but practical ones. |
| |
| Because we'd like to use our open-source |
| projects at Google and it's difficult to do so if those projects |
| use exceptions, we need to advise against exceptions in Google |
| open-source projects as well. |
| Things would probably be different if we had to do it all over |
| again from scratch. |
| </p> |
| <p> |
| There is an <a HREF="#Windows_Code">exception</a> to this |
| rule (no pun intended) for Windows code. |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Run-Time Type Information (RTTI)"> |
| <SUMMARY> |
| Avoid using Run Time Type Information (RTTI). |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| RTTI allows a programmer to query the C++ class of an |
| object at run time. This is done by use of <code>typeid</code> or |
| <code>dynamic_cast</code>. |
| </DEFINITION> |
| <CONS> |
| <p> |
| Querying the type of an object at run-time frequently means a |
| design problem. Needing to know the type of an |
| object at runtime is often an indication that |
| the design of your class hierarchy is flawed. |
| </p> |
| <p> |
| Undisciplined use of RTTI makes code hard to maintain. It can |
| lead to type-based decision trees or switch statements scattered |
| throughout the code, all of which must be examined when making |
| further changes. |
| </p> |
| </CONS> |
| <PROS> |
| <p> |
| The standard alternatives to RTTI (described below) require |
| modification or redesign of the class hierarchy in question. |
| Sometimes such modifications are infeasible or undesirable, |
| particularly in widely-used or mature code. |
| </p> |
| <p> |
| RTTI can be useful in some unit tests. For example, it is useful in |
| tests of factory classes where the test has to verify that a |
| newly created object has the expected dynamic type. It is also |
| useful in managing the relationship between objects and their mocks. |
| </p> |
| <p> |
| RTTI is useful when considering multiple abstract objects. Consider |
| <CODE_SNIPPET> |
| bool Base::Equal(Base* other) = 0; |
| bool Derived::Equal(Base* other) { |
| Derived* that = dynamic_cast<Derived*>(other); |
| if (that == NULL) |
| return false; |
| ... |
| } |
| </CODE_SNIPPET> |
| </p> |
| |
| </PROS> |
| <DECISION> |
| <p> |
| RTTI has legitimate uses but is prone to abuse, so you must |
| be careful when using it. You may use it freely |
| in unittests, but avoid it when possible in other code. |
| In particular, think twice before using RTTI in new code. |
| If you find yourself needing to write code that behaves differently |
| based on the class of an object, consider one of the following |
| alternatives to querying the type: |
| <ul> |
| <li> |
| Virtual methods are the preferred way of executing different |
| code paths depending on a specific subclass type. This puts |
| the work within the object itself. |
| </li> |
| <li> |
| If the work belongs outside the object and instead in some |
| processing code, consider a double-dispatch solution, such |
| as the Visitor design pattern. This allows a facility |
| outside the object itself to determine the type of class |
| using the built-in type system. |
| </li> |
| </ul> |
| </p> |
| <p> |
| When the logic of a program guarantees that a given instance |
| of a base class is in fact an instance of a particular derived class, |
| then a <code>dynamic_cast</code> may be used freely on the object. |
| |
| Usually one can use a |
| <code>static_cast</code> as an alternative in such situations. |
| </p> |
| <p> |
| Decision trees based on type are a strong indication that your |
| code is on the wrong track. |
| <BAD_CODE_SNIPPET> |
| if (typeid(*data) == typeid(D1)) { |
| ... |
| } else if (typeid(*data) == typeid(D2)) { |
| ... |
| } else if (typeid(*data) == typeid(D3)) { |
| ... |
| </BAD_CODE_SNIPPET> |
| Code such as this usually breaks when additional subclasses are |
| added to the class hierarchy. Moreover, when properties of a subclass |
| change, it is difficult to find and modify all the affected code segments. |
| </p> |
| <p> |
| Do not hand-implement an RTTI-like workaround. The arguments |
| against RTTI apply just as much to workarounds like class |
| hierarchies with type tags. Moreover, workarounds disguise your |
| true intent. |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Casting"> |
| <SUMMARY> |
| Use C++ casts like <code>static_cast<>()</code>. Do not use |
| other cast formats like <code>int y = (int)x;</code> or |
| <code>int y = int(x);</code>. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| C++ introduced a different cast system from C that |
| distinguishes the types of cast operations. |
| </DEFINITION> |
| <PROS> |
| The problem with C casts is the ambiguity of the operation; |
| sometimes you are doing a <em>conversion</em> (e.g., |
| <code>(int)3.5</code>) and sometimes you are doing a |
| <em>cast</em> (e.g., <code>(int)"hello"</code>); C++ casts |
| avoid this. Additionally C++ casts are more visible when |
| searching for them. |
| </PROS> |
| <CONS> |
| The syntax is nasty. |
| </CONS> |
| <DECISION> |
| <p> |
| Do not use C-style casts. Instead, use these C++-style |
| casts. |
| |
| </p> |
| <ul> |
| |
| <li> Use <code>static_cast</code> as the equivalent of a |
| C-style cast that does value conversion, or when you need to explicitly up-cast |
| a pointer from a class to its superclass. |
| </li> |
| <li> Use <code>const_cast</code> to remove the <code>const</code> |
| qualifier (see <a HREF="#Use_of_const">const</a>). |
| </li> |
| |
| |
| <li> Use <code>reinterpret_cast</code> to do unsafe |
| conversions of pointer types to and from integer and |
| other pointer types. Use this only if you know what you are |
| doing and you understand the aliasing issues. |
| |
| </li> |
| </ul> |
| <p> See the <a href="#Run-Time_Type_Information__RTTI_">RTTI section</a> |
| for guidance on the use of <code>dynamic_cast</code>. |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Streams"> |
| <SUMMARY> |
| Use streams only for logging. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| Streams are a replacement for <code>printf()</code> and |
| <code>scanf()</code>. |
| </DEFINITION> |
| <PROS> |
| With streams, you do not need to know the type of the object |
| you are printing. You do not have problems with format |
| strings not matching the argument list. (Though with gcc, you |
| do not have that problem with <code>printf</code> either.) Streams |
| have automatic constructors and destructors that open and close the |
| relevant files. |
| </PROS> |
| <CONS> |
| Streams make it difficult to do functionality like |
| <code>pread()</code>. Some formatting (particularly the common |
| format string idiom <code>%.*s</code>) is difficult if not |
| impossible to do efficiently using streams without using |
| <code>printf</code>-like hacks. Streams do not support operator |
| reordering (the <code>%1s</code> directive), which is helpful for |
| internationalization. |
| </CONS> |
| <DECISION> |
| |
| <p> |
| Do not use streams, except where required by a logging interface. |
| Use <code>printf</code>-like routines instead. |
| </p> |
| <p> |
| There are various pros and cons to using streams, but in |
| this case, as in many other cases, consistency trumps the |
| debate. Do not use streams in your code. |
| </p> |
| |
| <SUBSECTION title="Extended Discussion"> |
| <p> |
| There has been debate on this issue, so this explains the |
| reasoning in greater depth. Recall the Only One Way |
| guiding principle: we want to make sure that whenever we |
| do a certain type of I/O, the code looks the same in all |
| those places. Because of this, we do not want to allow |
| users to decide between using streams or using |
| <code>printf</code> plus Read/Write/etc. Instead, we should |
| settle on one or the other. We made an exception for logging |
| because it is a pretty specialized application, and for |
| historical reasons. |
| </p> |
| <p> |
| Proponents of streams have argued that streams are the obvious |
| choice of the two, but the issue is not actually so clear. For |
| every advantage of streams they point out, there is an |
| equivalent disadvantage. The biggest advantage is that |
| you do not need to know the type of the object to be |
| printing. This is a fair point. But, there is a |
| downside: you can easily use the wrong type, and the |
| compiler will not warn you. It is easy to make this |
| kind of mistake without knowing when using streams. |
| </p> |
| <CODE_SNIPPET> |
| cout << this; // Prints the address |
| cout << *this; // Prints the contents |
| </CODE_SNIPPET> |
| <p> |
| The compiler does not generate an error because |
| <code><<</code> has been overloaded. We discourage |
| overloading for just this reason. |
| </p> |
| <p> |
| Some say <code>printf</code> formatting is ugly and hard to |
| read, but streams are often no better. Consider the following |
| two fragments, both with the same typo. Which is easier to |
| discover? |
| </p> |
| <CODE_SNIPPET> |
| cerr << "Error connecting to '" << foo->bar()->hostname.first |
| << ":" << foo->bar()->hostname.second << ": " << strerror(errno); |
| |
| fprintf(stderr, "Error connecting to '%s:%u: %s", |
| foo->bar()->hostname.first, foo->bar()->hostname.second, |
| strerror(errno)); |
| </CODE_SNIPPET> |
| <p> |
| And so on and so forth for any issue you might bring up. |
| (You could argue, "Things would be better with the right |
| wrappers," but if it is true for one scheme, is it not |
| also true for the other? Also, remember the goal is to |
| make the language smaller, not add yet more machinery that |
| someone has to learn.) |
| </p> |
| <p> |
| Either path would yield different advantages and |
| disadvantages, and there is not a clearly superior |
| solution. The simplicity doctrine mandates we settle on |
| one of them though, and the majority decision was on |
| <code>printf</code> + <code>read</code>/<code>write</code>. |
| </p> |
| </SUBSECTION> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Preincrement and Predecrement"> |
| <SUMMARY> |
| Use prefix form (<code>++i</code>) of the increment and |
| decrement operators with iterators and other template objects. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| When a variable is incremented (<code>++i</code> or |
| <code>i++</code>) or decremented (<code>--i</code> or |
| <code>i--</code>) and the value of the expression is not used, |
| one must decide whether to preincrement (decrement) or |
| postincrement (decrement). |
| </DEFINITION> |
| <PROS> |
| When the return value is ignored, the "pre" form |
| (<code>++i</code>) is never less efficient than the "post" |
| form (<code>i++</code>), and is often more efficient. This is |
| because post-increment (or decrement) requires a copy of |
| <code>i</code> to be made, which is the value of the |
| expression. If <code>i</code> is an iterator or other |
| non-scalar type, copying <code>i</code> could be expensive. |
| Since the two types of increment behave the same when the |
| value is ignored, why not just always pre-increment? |
| </PROS> |
| <CONS> |
| The tradition developed, in C, of using post-increment when |
| the expression value is not used, especially in <code>for</code> |
| loops. Some find post-increment easier to read, since the |
| "subject" (<code>i</code>) precedes the "verb" (<code>++</code>), |
| just like in English. |
| </CONS> |
| <DECISION> |
| For simple scalar (non-object) values there is no reason to |
| prefer one form and we allow either. For iterators and other |
| template types, use pre-increment. |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Use of const"> |
| <SUMMARY> |
| Use <code>const</code> whenever it makes sense. |
| With C++11, |
| <code>constexpr</code> is a better choice for some uses of const. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| Declared variables and parameters can be preceded by the |
| keyword <code>const</code> to indicate the variables are not |
| changed (e.g., <code>const int foo</code>). Class functions |
| can have the <code>const</code> qualifier to indicate the |
| function does not change the state of the class member |
| variables (e.g., <code>class Foo { int Bar(char c) const; |
| };</code>). |
| </DEFINITION> |
| <PROS> |
| Easier for people to understand how variables are being used. |
| Allows the compiler to do better type checking, and, |
| conceivably, generate better code. Helps people convince |
| themselves of program correctness because they know the |
| functions they call are limited in how they can modify your |
| variables. Helps people know what functions are safe to use |
| without locks in multi-threaded programs. |
| </PROS> |
| <CONS> |
| <code>const</code> is viral: if you pass a <code>const</code> |
| variable to a function, that function must have <code>const</code> |
| in its prototype (or the variable will need a |
| <code>const_cast</code>). This can be a particular problem |
| when calling library functions. |
| </CONS> |
| <DECISION> |
| <p> |
| <code>const</code> variables, data members, methods and |
| arguments add a level of compile-time type checking; it |
| is better to detect errors as soon as possible. |
| Therefore we strongly recommend that you use |
| <code>const</code> whenever it makes sense to do so: |
| </p> |
| <ul> |
| <li> If a function does not modify an argument passed by |
| reference or by pointer, that argument should be |
| <code>const</code>. |
| </li> |
| <li> Declare methods to be <code>const</code> whenever |
| possible. Accessors should almost always be |
| <code>const</code>. Other methods should be const if they do |
| not modify any data members, do not call any |
| non-<code>const</code> methods, and do not return a |
| non-<code>const</code> pointer or non-<code>const</code> |
| reference to a data member. |
| </li> |
| <li> Consider making data members <code>const</code> |
| whenever they do not need to be modified after |
| construction. |
| </li> |
| </ul> |
| <p> |
| The <code>mutable</code> keyword is allowed but is unsafe |
| when used with threads, so thread safety should be carefully |
| considered first. |
| </p> |
| </DECISION> |
| <SUBSECTION title="Where to put the const"> |
| <p> |
| Some people favor the form <code>int const *foo</code> to |
| <code>const int* foo</code>. They argue that this is more |
| readable because it's more consistent: it keeps the rule |
| that <code>const</code> always follows the object it's |
| describing. However, this consistency argument doesn't |
| apply in codebases with few deeply-nested pointer |
| expressions since most <code>const</code> expressions have |
| only one <code>const</code>, and it applies to the |
| underlying value. In such cases, there's no consistency to |
| maintain. |
| Putting the <code>const</code> first is arguably more readable, |
| since it follows English in putting the "adjective" |
| (<code>const</code>) before the "noun" (<code>int</code>). |
| </p> |
| <p> |
| That said, while we encourage putting <code>const</code> first, |
| we do not require it. But be consistent with the code around |
| you! |
| </p> |
| </SUBSECTION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Use of constexpr"> |
| <SUMMARY> |
| In C++11, use <code>constexpr</code> |
| to define true constants or to ensure constant initialization. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| Some variables can be declared <code>constexpr</code> |
| to indicate the variables are true constants, |
| i.e. fixed at compilation/link time. |
| Some functions and constructors can be declared <code>constexpr</code> |
| which enables them to be used |
| in defining a <code>constexpr</code> variable. |
| </DEFINITION> |
| <PROS> |
| Use of <code>constexpr</code> enables |
| definition of constants with floating-point expressions |
| rather than just literals; |
| definition of constants of user-defined types; and |
| definition of constants with function calls. |
| </PROS> |
| <CONS> |
| Prematurely marking something as constexpr |
| may cause migration problems if later on it has to be downgraded. |
| |
| Current restrictions on what is allowed |
| in constexpr functions and constructors |
| may invite obscure workarounds in these definitions. |
| </CONS> |
| <DECISION> |
| <p> |
| <code>constexpr</code> definitions enable a more robust |
| specification of the constant parts of an interface. |
| Use <code>constexpr</code> to specify true constants |
| and the functions that support their definitions. |
| Avoid complexifying function definitions to enable |
| their use with <code>constexpr</code>. |
| Do not use <code>constexpr</code> to force inlining. |
| </p> |
| |
| |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Integer Types"> |
| <SUMMARY> |
| Of the built-in C++ integer types, the only one used |
| |
| is <code>int</code>. If a program needs a variable of a different |
| size, use |
| |
| a precise-width integer type from |
| <code><stdint.h></code>, such as <code>int16_t</code>. If |
| your variable represents a value that could ever be greater than or |
| equal to 2^31 (2GiB), use a 64-bit type such as <code>int64_t</code>. |
| Keep in mind that even if your value won't ever be too large for an |
| <code>int</code>, it may be used in intermediate calculations which may |
| require a larger type. When in doubt, choose a larger type. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| C++ does not specify the sizes of its integer types. Typically |
| people assume that <code>short</code> is 16 bits, |
| <code>int</code> is 32 bits, <code>long</code> is 32 bits and |
| <code>long long</code> is 64 bits. |
| </DEFINITION> |
| <PROS> |
| Uniformity of declaration. |
| </PROS> |
| <CONS> |
| The sizes of integral types in C++ can vary based on compiler |
| and architecture. |
| </CONS> |
| <DECISION> |
| <p> |
| |
| <code><stdint.h></code> defines |
| types like <code>int16_t</code>, <code>uint32_t</code>, |
| <code>int64_t</code>, etc. |
| You should always use those in preference to |
| <code>short</code>, <code>unsigned long long</code> and the |
| like, when you need a guarantee on the size of an integer. |
| Of the C integer types, only <code>int</code> should be |
| used. When appropriate, you are welcome to use standard |
| types like <code>size_t</code> and <code>ptrdiff_t</code>. |
| </p> |
| <p> |
| We use <code>int</code> very often, for integers we know are not |
| going to be too big, e.g., loop counters. Use plain old |
| <code>int</code> for such things. You should assume that an |
| <code>int</code> is |
| |
| at least 32 bits, |
| but don't assume that it has more than 32 bits. |
| If you need a 64-bit integer type, use |
| <code>int64_t</code> or |
| <code>uint64_t</code>. |
| </p> |
| <p> |
| For integers we know can be "big", |
| use |
| <code>int64_t</code>. |
| |
| </p> |
| <p> |
| You should not use the unsigned integer types such as |
| <code>uint32_t</code>, |
| unless there is a valid reason such as representing a bit pattern |
| rather than a number, or you need defined overflow modulo 2^N. |
| In particular, do not use unsigned types to say a number will never |
| be negative. Instead, use |
| |
| assertions for this. |
| </p> |
| |
| <p> |
| If your code is a container that returns a size, be sure to use |
| a type that will accommodate any possible usage of your container. |
| When in doubt, use a larger type rather than a smaller type. |
| </p> |
| <p> |
| Use care when converting integer types. Integer conversions and |
| promotions can cause non-intuitive behavior. |
| |
| </p> |
| </DECISION> |
| |
| <SUBSECTION title="On Unsigned Integers"> |
| <p> |
| Some people, including some textbook authors, recommend |
| using unsigned types to represent numbers that are never |
| negative. This is intended as a form of self-documentation. |
| However, in C, the advantages of such documentation are |
| outweighed by the real bugs it can introduce. Consider: |
| </p> |
| <CODE_SNIPPET> |
| for (unsigned int i = foo.Length()-1; i >= 0; --i) ... |
| </CODE_SNIPPET> |
| <p> |
| This code will never terminate! Sometimes gcc will notice |
| this bug and warn you, but often it will not. Equally bad |
| bugs can occur when comparing signed and unsigned |
| variables. Basically, C's type-promotion scheme causes |
| unsigned types to behave differently than one might expect. |
| </p> |
| <p> |
| So, document that a variable is non-negative using |
| assertions. |
| Don't use an unsigned type. |
| </p> |
| </SUBSECTION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="64-bit Portability"> |
| <SUMMARY> |
| Code should be 64-bit and 32-bit friendly. Bear in mind problems of |
| printing, comparisons, and structure alignment. |
| </SUMMARY> |
| <BODY> |
| <ul> |
| <li> |
| <p> |
| <code>printf()</code> specifiers for some types are |
| not cleanly portable between 32-bit and 64-bit |
| systems. C99 defines some portable format |
| specifiers. Unfortunately, MSVC 7.1 does not |
| understand some of these specifiers and the |
| standard is missing a few, so we have to define our |
| own ugly versions in some cases (in the style of the |
| standard include file <code>inttypes.h</code>): |
| </p> |
| <CODE_SNIPPET> |
| // printf macros for size_t, in the style of inttypes.h |
| #ifdef _LP64 |
| #define __PRIS_PREFIX "z" |
| #else |
| #define __PRIS_PREFIX |
| #endif |
| |
| // Use these macros after a % in a printf format string |
| // to get correct 32/64 bit behavior, like this: |
| // size_t size = records.size(); |
| // printf("%"PRIuS"\n", size); |
| |
| #define PRIdS __PRIS_PREFIX "d" |
| #define PRIxS __PRIS_PREFIX "x" |
| #define PRIuS __PRIS_PREFIX "u" |
| #define PRIXS __PRIS_PREFIX "X" |
| #define PRIoS __PRIS_PREFIX "o" |
| </CODE_SNIPPET> |
| <table border="1" summary="portable printf specifiers"> |
| <TBODY> |
| <tr align="center"> |
| <th>Type</th> |
| <th>DO NOT use</th> |
| <th>DO use</th> |
| <th>Notes</th> |
| </tr> |
| <tr align="center"> |
| <td><code>void *</code> (or any pointer)</td> |
| <td><code>%lx</code></td> |
| <td><code>%p</code></td> |
| <td> </td> |
| </tr> |
| |
| <tr align="center"> |
| <td><code>int64_t</code></td> |
| <td><code>%qd</code>, |
| <code>%lld</code></td> |
| <td><code>%"PRId64"</code></td> |
| <td/> |
| </tr> |
| |
| <tr align="center"> |
| <td><code>uint64_t</code></td> |
| <td><code>%qu</code>, |
| <code>%llu</code>, |
| <code>%llx</code></td> |
| <td><code>%"PRIu64"</code>, |
| <code>%"PRIx64"</code></td> |
| <td/> |
| </tr> |
| |
| <tr align="center"> |
| <td><code>size_t</code></td> |
| <td><code>%u</code></td> |
| <td><code>%"PRIuS"</code>, |
| <code>%"PRIxS"</code></td> |
| <td>C99 specifies <code>%zu</code></td> |
| </tr> |
| <tr align="center"> |
| <td><code>ptrdiff_t</code></td> |
| <td><code>%d</code></td> |
| <td><code>%"PRIdS"</code></td> |
| <td>C99 specifies <code>%zd</code></td> |
| </tr> |
| |
| </TBODY> |
| </table> |
| <p> |
| Note that the <code>PRI*</code> macros expand to independent |
| strings which are concatenated by the compiler. Hence |
| if you are using a non-constant format string, you |
| need to insert the value of the macro into the format, |
| rather than the name. It is still possible, as usual, |
| to include length specifiers, etc., after the |
| <code>%</code> when using the <code>PRI*</code> |
| macros. So, e.g. <code>printf("x = %30"PRIuS"\n", |
| x)</code> would expand on 32-bit Linux to |
| <code>printf("x = %30" "u" "\n", x)</code>, which the |
| compiler will treat as <code>printf("x = %30u\n", |
| x)</code>. |
| </p> |
| |
| </li> |
| |
| <li> Remember that <code>sizeof(void *)</code> != |
| <code>sizeof(int)</code>. Use <code>intptr_t</code> if |
| you want a pointer-sized integer. |
| </li> |
| |
| <li> You may need to be careful with structure alignments, |
| particularly for structures being stored on disk. Any |
| class/structure with a |
| |
| <code>int64_t</code>/<code>uint64_t</code> |
| member will by default end up being 8-byte aligned on a 64-bit |
| system. If you have such structures being shared on disk |
| between 32-bit and 64-bit code, you will need to ensure |
| that they are packed the same on both architectures. |
| |
| Most compilers offer a way to alter |
| structure alignment. For gcc, you can use |
| <code>__attribute__((packed))</code>. MSVC offers |
| <code>#pragma pack()</code> and |
| <code>__declspec(align())</code>. |
| </li> |
| |
| <li> |
| |
| Use the <code>LL</code> or <code>ULL</code> suffixes as |
| needed to create 64-bit constants. For example: |
| |
| <CODE_SNIPPET> |
| int64_t my_value = 0x123456789LL; |
| uint64_t my_mask = 3ULL << 48; |
| </CODE_SNIPPET> |
| </li> |
| |
| <li> If you really need different code on 32-bit and 64-bit |
| systems, use <code>#ifdef _LP64</code> to choose between |
| the code variants. (But please avoid this if |
| possible, and keep any such changes localized.) |
| </li> |
| </ul> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Preprocessor Macros"> |
| <SUMMARY> |
| Be very cautious with macros. Prefer inline functions, enums, |
| and <code>const</code> variables to macros. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Macros mean that the code you see is not the same as the code |
| the compiler sees. This can introduce unexpected behavior, |
| especially since macros have global scope. |
| </p> |
| <p> |
| Luckily, macros are not nearly as necessary in C++ as they are |
| in C. Instead of using a macro to inline performance-critical |
| code, use an inline function. Instead of using a macro to |
| store a constant, use a <code>const</code> variable. Instead of |
| using a macro to "abbreviate" a long variable name, use a |
| reference. Instead of using a macro to conditionally compile code |
| ... well, don't do that at all (except, of course, for the |
| <code>#define</code> guards to prevent double inclusion of |
| header files). It makes testing much more difficult. |
| </p> |
| <p> |
| Macros can do things these other techniques cannot, and you do |
| see them in the codebase, especially in the lower-level |
| libraries. And some of their special features (like |
| stringifying, concatenation, and so forth) are not available |
| through the language proper. But before using a macro, |
| consider carefully whether there's a non-macro way to achieve |
| the same result. |
| </p> |
| <p> |
| The following usage pattern will avoid many problems with |
| macros; if you use macros, follow it whenever possible: |
| </p> |
| <ul> |
| <li> Don't define macros in a <code>.h</code> file. |
| </li> |
| <li> <code>#define</code> macros right before you use them, |
| and <code>#undef</code> them right after. |
| </li> |
| <li> Do not just <code>#undef</code> an existing macro before |
| replacing it with your own; instead, pick a name that's |
| likely to be unique. |
| </li> |
| <li> Try not to use macros that expand to unbalanced C++ |
| constructs, or at least document that behavior well. |
| </li> |
| <li> Prefer not using <code>##</code> to generate function/class/variable |
| names. |
| </li> |
| </ul> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="0 and nullptr/NULL"> |
| <SUMMARY> |
| Use <code>0</code> for integers, <code>0.0</code> for reals, |
| <code>nullptr</code> (or <code>NULL</code>) for pointers, |
| and <code>'\0'</code> for chars. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Use <code>0</code> for integers and <code>0.0</code> for reals. |
| This is not controversial. |
| </p> |
| <p> |
| |
| |
| For pointers (address values), there is a choice between <code>0</code> |
| and <code>NULL</code> (and, for C++11, <code>nullptr</code>). |
| For projects that allow C++11 features, use <code>nullptr</code>. |
| For C++03 projects, we prefer <code>NULL</code> because it looks like a |
| pointer. In fact, some C++ compilers provide special definitions of |
| <code>NULL</code> which enable them to give useful warnings, |
| particularly in situations where <code>sizeof(NULL)</code> is not equal |
| to <code>sizeof(0)</code>. |
| |
| </p> |
| <p> |
| Use <code>'\0'</code> for chars. |
| This is the correct type and also makes code more readable. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="sizeof"> |
| <SUMMARY> |
| Prefer <code>sizeof(<var>varname</var>)</code> to |
| <code>sizeof(<var>type</var>)</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Use <code>sizeof(<var>varname</var>)</code> |
| when you take the size of a particular variable. |
| <code>sizeof(<var>varname</var>)</code> will update |
| appropriately if someone changes the variable type |
| either now or later. |
| You may use <code>sizeof(<var>type</var>)</code> |
| for code unrelated to any particular variable, |
| such as code that manages an external or internal |
| data format where a variable of an appropriate C++ type |
| is not convenient. |
| </p> |
| <p> |
| <CODE_SNIPPET> |
| Struct data; |
| memset(&data, 0, sizeof(data)); |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| memset(&data, 0, sizeof(Struct)); |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| if (raw_size < sizeof(int)) { |
| LOG(ERROR) << "compressed record not big enough for count: " << raw_size; |
| return false; |
| } |
| </CODE_SNIPPET> |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="auto"> |
| <SUMMARY> |
| Use <code>auto</code> to avoid type names that are just clutter. |
| Continue to use manifest type declarations when it helps readability, |
| and never use <code>auto</code> for anything but local variables. |
| |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| In C++11, a variable whose type is given as <code>auto</code> will be given |
| a type that matches that of the expression used to initialize |
| it. You can use <code>auto</code> either to initialize a |
| variable by copying, or to bind a reference. |
| <CODE_SNIPPET> |
| vector<string> v; |
| ... |
| auto s1 = v[0]; // Makes a copy of v[0]. |
| const auto& s2 = v[0]; // s2 is a reference to v[0]. |
| </CODE_SNIPPET> |
| </DEFINITION> |
| <PROS> |
| <p> |
| C++ type names can sometimes be long and cumbersome, |
| especially when they involve templates or namespaces. In a statement like |
| <CODE_SNIPPET> |
| sparse_hash_map<string, int>::iterator iter = m.find(val); |
| </CODE_SNIPPET> |
| the return type is hard to read, and obscures the primary |
| purpose of the statement. Changing it to |
| <CODE_SNIPPET> |
| auto iter = m.find(val); |
| </CODE_SNIPPET> |
| makes it more readable. |
| </p> |
| <p> |
| Without <code>auto</code> we are sometimes forced to write a |
| type name twice in the same expression, adding no value |
| for the reader, as in |
| <CODE_SNIPPET> |
| diagnostics::ErrorStatus* status = new diagnostics::ErrorStatus("xyz"); |
| </CODE_SNIPPET> |
| </p> |
| <p> |
| Using <code>auto</code> makes it easier to use intermediate |
| variables when appropriate, by reducing the burden of writing |
| their types explicitly. |
| </p> |
| </PROS> |
| <CONS> |
| <p>Sometimes code is clearer when types are manifest, especially when |
| a variable's initialization depends on things that were declared |
| far away. In an expression like |
| <CODE_SNIPPET> |
| auto i = x.Lookup(key); |
| </CODE_SNIPPET> |
| it may not be obvious what <code>i</code>'s type is, if <code>x</code> |
| was declared hundreds of lines earlier. |
| </p> |
| |
| <p>Programmers have to understand the difference between <code>auto</code> |
| and <code>const auto&</code> or they'll get copies when |
| they didn't mean to. |
| </p> |
| |
| <p>The interaction between <code>auto</code> and C++11 |
| brace-initialization can be confusing. (C++11 brace-initialization |
| isn't an approved feature, but this may become relevant when and |
| if it is permitted.) The declarations |
| <CODE_SNIPPET> |
| auto x(3); // Note: parentheses. |
| auto y{3}; // Note: curly braces. |
| </CODE_SNIPPET> |
| mean different things — <code>x</code> is |
| an <code>int</code>, while <code>y</code> is |
| an <code>initializer_list</code>. The same applies to other |
| normally-invisible proxy types. |
| |
| </p> |
| |
| <p>If an <code>auto</code> variable is used as part of an |
| interface, e.g. as a constant in a header, then a programmer |
| might change its type while only intending to change its |
| value, leading to a more radical API change than intended.</p> |
| </CONS> |
| <DECISION> |
| <p><code>auto</code> is permitted, for local variables only. |
| Do not use <code>auto</code> for file-scope or namespace-scope |
| variables, or for class members.</p> |
| <p>The <code>auto</code> keyword is also used in an unrelated |
| C++11 feature: it's part of the syntax for a new kind of |
| function declaration with a trailing return type. Function |
| declarations with trailing return types are not permitted.</p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Boost"> |
| <SUMMARY> |
| Use only approved libraries from the Boost library collection. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| The <a href="http://www.boost.org/">Boost library collection</a> is |
| a popular collection of peer-reviewed, free, open-source C++ libraries. |
| </DEFINITION> |
| <PROS> |
| Boost code is generally very high-quality, is widely portable, and fills |
| many important gaps in the C++ standard library, such as type traits, |
| better binders, and better smart pointers. It also provides an |
| implementation of the TR1 extension to the standard library. |
| </PROS> |
| <CONS> |
| Some Boost libraries encourage coding practices which can hamper |
| readability, such as metaprogramming and other advanced template |
| techniques, and an excessively "functional" style of programming. |
| |
| </CONS> |
| <DECISION> |
| |
| <div> |
| |
| In order to maintain a high level of readability for all contributors |
| who might read and maintain code, we only allow an approved subset of |
| Boost features. Currently, the following libraries are permitted: |
| <ul> |
| <li> <a href="http://www.boost.org/libs/utility/call_traits.htm"> |
| Call Traits</a> from <code>boost/call_traits.hpp</code> |
| </li> |
| <li> <a href="http://www.boost.org/libs/utility/compressed_pair.htm"> |
| Compressed Pair</a> from <code>boost/compressed_pair.hpp</code> |
| </li> |
| <li> <a href="http://www.boost.org/libs/ptr_container/"> |
| Pointer Container</a> from <code>boost/ptr_container</code> except |
| serialization and wrappers for containers not in the C++03 |
| standard (<code>ptr_circular_buffer.hpp</code> and |
| <code>ptr_unordered*</code>) |
| </li> |
| <li> <a href="http://www.boost.org/libs/array/"> |
| Array</a> from <code>boost/array.hpp</code> |
| </li> |
| <li> <a href="http://www.boost.org/libs/graph/"> |
| The Boost Graph Library (BGL)</a> from <code>boost/graph</code>, |
| except serialization (<code>adj_list_serialize.hpp</code>) and |
| parallel/distributed algorithms and data structures |
| (<code>boost/graph/parallel/*</code> and |
| <code>boost/graph/distributed/*</code>). |
| </li> |
| <li> <a href="http://www.boost.org/libs/property_map/"> |
| Property Map</a> from <code>boost/property_map</code>, except |
| parallel/distributed property maps |
| (<code>boost/property_map/parallel/*</code>). |
| </li> |
| <li> The part of |
| <a href="http://www.boost.org/libs/iterator/"> |
| Iterator</a> that deals with defining iterators: |
| <code>boost/iterator/iterator_adaptor.hpp</code>, |
| <code>boost/iterator/iterator_facade.hpp</code>, and |
| <code>boost/function_output_iterator.hpp</code></li> |
| <li> The part of |
| <a href="http://www.boost.org/libs/polygon/"> |
| Polygon</a> that deals with Voronoi diagram construction and |
| doesn't depend on the rest of Polygon: |
| <code>boost/polygon/voronoi_builder.hpp</code>, |
| <code>boost/polygon/voronoi_diagram.hpp</code>, and |
| <code>boost/polygon/voronoi_geometry_type.hpp</code></li> |
| </ul> |
| We are actively considering adding other Boost features to the list, so |
| this rule may be relaxed in the future. |
| </div> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| |
| |
| <STYLEPOINT title="C++11"> |
| <SUMMARY> |
| Use only approved libraries and language extensions from C++11 (formerly |
| known as C++0x). |
| |
| Consider portability to other environments before |
| using C++11 features in your project. |
| </SUMMARY> |
| <BODY> |
| <DEFINITION> |
| C++11 is the latest ISO C++ standard. |
| It contains |
| <a href="http://en.wikipedia.org/wiki/C%2B%2B11">significant |
| changes</a> both to the language and libraries. |
| |
| </DEFINITION> |
| <PROS> |
| C++11 has become the official standard, and eventually will |
| be supported by most C++ compilers. It standardizes some common C++ |
| extensions that we use already, allows shorthands for some operations, |
| and has some performance and safety improvements. |
| </PROS> |
| <CONS> |
| <p> |
| The C++11 standard is substantially more complex than its predecessor |
| (1,300 pages versus 800 pages), and is |
| unfamiliar to many developers. The long-term effects of some |
| features on code readability and maintenance are unknown. We cannot |
| predict when its various features will be implemented uniformly by |
| tools that may be of interest (gcc, icc, clang, Eclipse, etc.). |
| </p> |
| <p> |
| As with <a href="#Boost">Boost</a>, some C++11 extensions encourage |
| coding practices that hamper readability—for example by removing |
| checked redundancy (such as type names) that may be helpful to readers, |
| or by encouraging template metaprogramming. Other extensions |
| duplicate functionality available through existing |
| mechanisms, which may lead to |
| confusion and conversion costs. |
| </p> |
| </CONS> |
| <DECISION> |
| Use only C++11 libraries and language features that have been approved |
| for use. |
| Currently only the following C++11 features are approved: |
| <ul> |
| <li><code>auto</code> (for local variables only).</li> |
| <li> |
| <code>constexpr</code> (for ensuring constants).</li> |
| <li>Use of <code>>></code> with no intervening space to |
| close multiple levels of template arguments, as in |
| <code>set<list<string>></code>, |
| where C++03 required a space as in |
| <code>set<list<string> ></code>. |
| </li> |
| <li>Range-based |
| <code>for</code> loops.</li> |
| <li>Use of the <code>LL</code> and <code>ULL</code> suffixes on |
| numeric literals to guarantee that their type is at least 64 bits |
| wide.</li> |
| <li>Variadic macros (but note |
| that use of macros is discouraged).</li> |
| <li>All of the new STL algorithms in the |
| <a href="http://en.cppreference.com/w/cpp/algorithm"><algorithm></a> |
| and <a href="http://en.cppreference.com/w/cpp/numeric"><numeric></a> |
| headers, except for the versions of |
| <code>min</code>, <code>max</code>, and <code>minmax</code> |
| whose signatures contain initializer lists.</li> |
| <li>Use of local types as template parameters.</li> |
| <li><code>nullptr</code> and <code>nullptr_t</code>.</li> |
| <li><code>static_assert</code>.</li> |
| <li>Everything in <a href="http://en.cppreference.com/w/cpp/header/tuple"><tuple></a>. |
| </li> |
| </ul> |
| Other features will be approved individually as appropriate. |
| Avoid writing code that is incompatible with C++11 (even though it |
| works in C++03). |
| |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| </CATEGORY> |
| |
| <CATEGORY title="Naming"> |
| <p> |
| The most important consistency rules are those that govern |
| naming. The style of a name immediately informs us what sort of |
| thing the named entity is: a type, a variable, a function, a |
| constant, a macro, etc., without requiring us to search for the |
| declaration of that entity. The pattern-matching engine in our |
| brains relies a great deal on these naming rules. |
| |
| </p> |
| <p> |
| Naming rules are pretty arbitrary, but |
| |
| we feel that consistency is more important than individual preferences |
| in this area, so regardless of whether you find them sensible or not, |
| the rules are the rules. |
| </p> |
| |
| <STYLEPOINT title="General Naming Rules"> |
| <SUMMARY> |
| Function names, variable names, and filenames should be |
| descriptive; eschew abbreviation. Types and variables should be |
| nouns, while functions should be "command" verbs. |
| </SUMMARY> |
| <BODY> |
| <SUBSECTION title="How to Name"> |
| <p> |
| Give as descriptive a name as possible, within reason. Do |
| not worry about saving horizontal space as it is far more |
| important to make your code immediately understandable by a |
| new reader. Examples of well-chosen names: |
| </p> |
| <CODE_SNIPPET> |
| int num_errors; // Good. |
| int num_completed_connections; // Good. |
| </CODE_SNIPPET> |
| <p> |
| Poorly-chosen names use ambiguous abbreviations or arbitrary |
| characters that do not convey meaning: |
| </p> |
| <BAD_CODE_SNIPPET> |
| int n; // Bad - meaningless. |
| int nerr; // Bad - ambiguous abbreviation. |
| int n_comp_conns; // Bad - ambiguous abbreviation. |
| </BAD_CODE_SNIPPET> |
| <p> |
| Type and variable names should typically be nouns: e.g., |
| <code>FileOpener</code>, |
| |
| <code>num_errors</code>. |
| </p> |
| <p> |
| Function names should typically be imperative (that is they |
| should be commands): e.g., <code>OpenFile()</code>, |
| <code>set_num_errors()</code>. There is an exception for |
| accessors, which, described more completely in <a HREF="#Function_Names">Function Names</a>, should be named |
| the same as the variable they access. |
| </p> |
| </SUBSECTION> |
| |
| <SUBSECTION title="Abbreviations"> |
| <p> |
| Do not use abbreviations unless they are extremely well |
| known outside your project. For example: |
| </p> |
| <CODE_SNIPPET> |
| // Good |
| // These show proper names with no abbreviations. |
| int num_dns_connections; // Most people know what "DNS" stands for. |
| int price_count_reader; // OK, price count. Makes sense. |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| // Bad! |
| // Abbreviations can be confusing or ambiguous outside a small group. |
| int wgc_connections; // Only your group knows what this stands for. |
| int pc_reader; // Lots of things can be abbreviated "pc". |
| </BAD_CODE_SNIPPET> |
| <p> |
| Never abbreviate by leaving out letters: |
| </p> |
| <CODE_SNIPPET> |
| int error_count; // Good. |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| int error_cnt; // Bad. |
| </BAD_CODE_SNIPPET> |
| </SUBSECTION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="File Names"> |
| <SUMMARY> |
| Filenames should be all lowercase and can include underscores |
| (<code>_</code>) or dashes (<code>-</code>). Follow the |
| convention that your |
| |
| project |
| uses. If there is no consistent local pattern to follow, prefer "_". |
| </SUMMARY> |
| <BODY> |
| <p> |
| Examples of acceptable file names: |
| </p> |
| <p> |
| <code> |
| my_useful_class.cc<br/> |
| my-useful-class.cc<br/> |
| myusefulclass.cc<br/> |
| myusefulclass_test.cc // _unittest and _regtest are deprecated.<br/> |
| </code> |
| </p> |
| <p> |
| C++ files should end in <code>.cc</code> and header files |
| should end in <code>.h</code>. |
| </p> |
| <p> |
| Do not use filenames that already exist |
| in <code>/usr/include</code>, such as <code>db.h</code>. |
| </p> |
| <p> |
| In general, make your filenames very specific. For example, |
| use <code>http_server_logs.h</code> rather |
| than <code>logs.h</code>. A very common case is to have a |
| pair of files called, e.g., <code>foo_bar.h</code> |
| and <code>foo_bar.cc</code>, defining a class |
| called <code>FooBar</code>. |
| </p> |
| <p> |
| Inline functions must be in a <code>.h</code> file. If your |
| inline functions are very short, they should go directly into your |
| <code>.h</code> file. However, if your inline functions |
| include a lot of code, they may go into a third file that |
| ends in <code>-inl.h</code>. In a class with a lot of inline |
| code, your class could have three files: |
| </p> |
| <CODE_SNIPPET> |
| url_table.h // The class declaration. |
| url_table.cc // The class definition. |
| url_table-inl.h // Inline functions that include lots of code. |
| </CODE_SNIPPET> |
| <p> |
| See also the section <a href="#The_-inl.h_Files">-inl.h Files</a> |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Type Names"> |
| <SUMMARY> |
| Type names start with a capital letter and have a capital |
| letter for each new word, with no underscores: |
| <code>MyExcitingClass</code>, <code>MyExcitingEnum</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| The names of all types — classes, structs, typedefs, and enums |
| — have the same naming convention. Type names should start |
| with a capital letter and have a capital letter for each new |
| word. No underscores. For example: |
| </p> |
| <CODE_SNIPPET> |
| // classes and structs |
| class UrlTable { ... |
| class UrlTableTester { ... |
| struct UrlTableProperties { ... |
| |
| // typedefs |
| typedef hash_map<UrlTableProperties *, string> PropertiesMap; |
| |
| // enums |
| enum UrlTableErrors { ... |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Variable Names"> |
| <SUMMARY> |
| Variable names are all lowercase, with underscores between |
| words. Class member variables have trailing underscores. For |
| instance: <code>my_exciting_local_variable</code>, |
| <code>my_exciting_member_variable_</code>. |
| </SUMMARY> |
| <BODY> |
| <SUBSECTION title="Common Variable names"> |
| <p> |
| For example: |
| </p> |
| <CODE_SNIPPET> |
| string table_name; // OK - uses underscore. |
| string tablename; // OK - all lowercase. |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| string tableName; // Bad - mixed case. |
| </BAD_CODE_SNIPPET> |
| </SUBSECTION> |
| |
| <SUBSECTION title="Class Data Members"> |
| <p> |
| Data members (also called instance variables or member |
| variables) are lowercase with optional underscores like |
| regular variable names, but always end with a trailing |
| underscore. |
| </p> |
| <CODE_SNIPPET> |
| string table_name_; // OK - underscore at end. |
| string tablename_; // OK. |
| </CODE_SNIPPET> |
| </SUBSECTION> |
| |
| <SUBSECTION title="Struct Variables"> |
| <p> |
| Data members in structs should be named like regular |
| variables without the trailing underscores that data members |
| in classes have. |
| </p> |
| <CODE_SNIPPET> |
| struct UrlTableProperties { |
| string name; |
| int num_entries; |
| } |
| </CODE_SNIPPET> |
| <p> |
| See <a HREF="#Structs_vs._Classes">Structs vs. Classes</a> for a |
| discussion of when to use a struct versus a class. |
| </p> |
| </SUBSECTION> |
| |
| <SUBSECTION title="Global Variables"> |
| <p> |
| There are no special requirements for global variables, |
| which should be rare in any case, but if you use one, |
| consider prefixing it with <code>g_</code> or some other |
| marker to easily distinguish it from local variables. |
| </p> |
| </SUBSECTION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Constant Names"> |
| <SUMMARY> |
| Use a <code>k</code> followed by mixed case: |
| <code>kDaysInAWeek</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| All compile-time constants, whether they are declared locally, |
| globally, or as part of a class, follow a slightly different |
| naming convention from other variables. Use a <code>k</code> |
| followed by words with uppercase first letters: |
| </p> |
| <CODE_SNIPPET> |
| const int kDaysInAWeek = 7; |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Function Names"> |
| <SUMMARY> |
| Regular functions have mixed case; accessors and mutators match |
| the name of the variable: <code>MyExcitingFunction()</code>, |
| <code>MyExcitingMethod()</code>, |
| <code>my_exciting_member_variable()</code>, |
| <code>set_my_exciting_member_variable()</code>. |
| </SUMMARY> |
| <BODY> |
| <SUBSECTION title="Regular Functions"> |
| <p> |
| Functions should start with a capital letter and have a |
| capital letter for each new word. No underscores. |
| </p> |
| <p> |
| If your function crashes upon an error, you should append OrDie to |
| the function name. This only applies to functions which could be |
| used by production code and to errors that are reasonably |
| likely to occur during normal operation. |
| </p> |
| <CODE_SNIPPET> |
| AddTableEntry() |
| DeleteUrl() |
| OpenFileOrDie() |
| </CODE_SNIPPET> |
| </SUBSECTION> |
| |
| <SUBSECTION title="Accessors and Mutators"> |
| <p> |
| Accessors and mutators (get and set functions) should match |
| the name of the variable they are getting and setting. This |
| shows an excerpt of a class whose instance variable is |
| <code>num_entries_</code>. |
| </p> |
| <CODE_SNIPPET> |
| class MyClass { |
| public: |
| ... |
| int num_entries() const { return num_entries_; } |
| void set_num_entries(int num_entries) { num_entries_ = num_entries; } |
| |
| private: |
| int num_entries_; |
| }; |
| </CODE_SNIPPET> |
| <p> |
| You may also use lowercase letters for other very short |
| inlined functions. For example if a function were so cheap |
| you would not cache the value if you were calling it in a |
| loop, then lowercase naming would be acceptable. |
| </p> |
| </SUBSECTION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Namespace Names"> |
| |
| <SUMMARY> |
| Namespace names are all lower-case, and based on project names and |
| possibly their directory structure: |
| <code>google_awesome_project</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| See <a HREF="#Namespaces">Namespaces</a> for a discussion of |
| namespaces and how to name them. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Enumerator Names"> |
| <SUMMARY> |
| Enumerators should be named <i>either</i> like |
| <A HREF="#Constant_Names">constants</A> or like |
| <A HREF="#Macro_Names">macros</A>: either <code>kEnumName</code> |
| or <code>ENUM_NAME</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Preferably, the individual enumerators should be named like |
| <A HREF="#Constant_Names">constants</A>. However, it is also |
| acceptable to name them like <A HREF="#Macro_Names">macros</A>. The enumeration name, |
| <code>UrlTableErrors</code> (and |
| <code>AlternateUrlTableErrors</code>), is a type, and |
| therefore mixed case. |
| </p> |
| <CODE_SNIPPET> |
| enum UrlTableErrors { |
| kOK = 0, |
| kErrorOutOfMemory, |
| kErrorMalformedInput, |
| }; |
| enum AlternateUrlTableErrors { |
| OK = 0, |
| OUT_OF_MEMORY = 1, |
| MALFORMED_INPUT = 2, |
| }; |
| </CODE_SNIPPET> |
| <p> |
| Until January 2009, the style was to name enum values like |
| <A HREF="#Macro_Names">macros</A>. This caused problems with |
| name collisions between enum values and macros. Hence, the |
| change to prefer constant-style naming was put in place. New |
| code should prefer constant-style naming if possible. |
| However, there is no reason to change old code to use |
| constant-style names, unless the old names are actually |
| causing a compile-time problem. |
| </p> |
| |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Macro Names"> |
| <SUMMARY> |
| You're not really going to <A HREF="#Preprocessor_Macros">define |
| a macro</A>, are you? If you do, they're like this: |
| <code>MY_MACRO_THAT_SCARES_SMALL_CHILDREN</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Please see the <a href="#Preprocessor_Macros">description of |
| macros</a>; in general macros should <em>not</em> be used. |
| However, if they are absolutely needed, then they should be |
| named with all capitals and underscores. |
| </p> |
| <CODE_SNIPPET> |
| #define ROUND(x) ... |
| #define PI_ROUNDED 3.0 |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Exceptions to Naming Rules"> |
| <SUMMARY> |
| If you are naming something that is analogous to an existing C |
| or C++ entity then you can follow the existing naming convention |
| scheme. |
| </SUMMARY> |
| <BODY> |
| <p> |
| <dl> |
| <dt> <code>bigopen()</code> </dt> |
| <dd> function name, follows form of <code>open()</code> </dd> |
| <dt> <code>uint</code> </dt> |
| <dd> <code>typedef</code> </dd> |
| <dt> <code>bigpos</code> </dt> |
| <dd> <code>struct</code> or <code>class</code>, follows form of |
| <code>pos</code> </dd> |
| <dt> <code>sparse_hash_map</code> </dt> |
| <dd> STL-like entity; follows STL naming conventions </dd> |
| <dt> <code>LONGLONG_MAX</code> </dt> |
| <dd> a constant, as in <code>INT_MAX</code> </dd> |
| </dl> |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="Comments"> |
| <p> |
| Though a pain to write, comments are absolutely vital to keeping our |
| code readable. The following rules describe what you should |
| comment and where. But remember: while comments are very |
| important, the best code is self-documenting. Giving sensible |
| names to types and variables is much better than using obscure |
| names that you must then explain through comments. |
| </p> |
| <p> |
| When writing your comments, write for your audience: the next |
| |
| contributor |
| who will need to understand your code. Be generous — the next |
| one may be you! |
| </p> |
| |
| <STYLEPOINT title="Comment Style"> |
| <SUMMARY> |
| Use either the <code>//</code> or <code>/* */</code> syntax, as long |
| as you are consistent. |
| </SUMMARY> |
| <BODY> |
| <p> |
| You can use either the <code>//</code> or the <code>/* */</code> |
| syntax; however, <code>//</code> is <em>much</em> more common. |
| Be consistent with how you comment and what style you use where. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="File Comments"> |
| <SUMMARY> |
| Start each file with license boilerplate, |
| followed by a description of its contents. |
| </SUMMARY> |
| <BODY> |
| <SUBSECTION title="Legal Notice and Author Line"> |
| |
| <p> |
| Every file should contain license boilerplate. |
| Choose the appropriate boilerplate for the license used by the project |
| (for example, Apache 2.0, BSD, LGPL, GPL). |
| </p> |
| <p> |
| If you make significant changes to a file with an author line, |
| consider deleting the author line. |
| </p> |
| </SUBSECTION> |
| |
| <SUBSECTION title="File Contents"> |
| <p> |
| Every file should have a comment at the top describing its contents. |
| </p> |
| <p> |
| Generally a <code>.h</code> file will describe the classes |
| that are declared in the file with an overview of what they |
| are for and how they are used. A <code>.cc</code> file |
| should contain more information about implementation details |
| or discussions of tricky algorithms. If you feel the |
| implementation details or a discussion of the algorithms |
| would be useful for someone reading the <code>.h</code>, |
| feel free to put it there instead, but mention in the |
| <code>.cc</code> that the documentation is in the |
| <code>.h</code> file. |
| </p> |
| <p> |
| Do not duplicate comments in both the <code>.h</code> and |
| the <code>.cc</code>. Duplicated comments diverge. |
| </p> |
| </SUBSECTION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Class Comments"> |
| <SUMMARY> |
| Every class definition should have an accompanying comment that |
| describes what it is for and how it should be used. |
| </SUMMARY> |
| <BODY> |
| <CODE_SNIPPET> |
| // Iterates over the contents of a GargantuanTable. Sample usage: |
| // GargantuanTableIterator* iter = table->NewIterator(); |
| // for (iter->Seek("foo"); !iter->done(); iter->Next()) { |
| // process(iter->key(), iter->value()); |
| // } |
| // delete iter; |
| class GargantuanTableIterator { |
| ... |
| }; |
| </CODE_SNIPPET> |
| <p> |
| If you have already described a class in detail in the |
| comments at the top of your file feel free to simply state |
| "See comment at top of file for a complete description", but |
| be sure to have some sort of comment. |
| </p> |
| <p> |
| Document the synchronization assumptions the class makes, if |
| any. If an instance of the class can be accessed by multiple |
| threads, take extra care to document the rules and invariants |
| surrounding multithreaded use. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Function Comments"> |
| <SUMMARY> |
| Declaration comments describe use of the function; comments at |
| the definition of a function describe operation. |
| </SUMMARY> |
| <BODY> |
| <SUBSECTION title="Function Declarations"> |
| <p> |
| Every function declaration should have comments immediately |
| preceding it that describe what the function does and how to |
| use it. These comments should be descriptive ("Opens the |
| file") rather than imperative ("Open the file"); the comment |
| describes the function, it does not tell the function what |
| to do. In general, these comments do not describe how the |
| function performs its task. Instead, that should be left to |
| comments in the function definition. |
| </p> |
| <p> |
| Types of things to mention in comments at the function |
| declaration: |
| </p> |
| <ul> |
| <li> What the inputs and outputs are. |
| </li> |
| <li> For class member functions: whether the object |
| remembers reference arguments beyond the |
| duration of the method call, and whether it will |
| free them or not. |
| </li> |
| <li> If the function allocates memory that the caller |
| must free. |
| </li> |
| <li> Whether any of the arguments can be a null pointer. |
| </li> |
| <li> If there are any performance implications of how a |
| function is used. |
| </li> |
| <li> If the function is re-entrant. What are its |
| synchronization assumptions? |
| </li> |
| </ul> |
| <p> |
| Here is an example: |
| </p> |
| <CODE_SNIPPET> |
| // Returns an iterator for this table. It is the client's |
| // responsibility to delete the iterator when it is done with it, |
| // and it must not use the iterator once the GargantuanTable object |
| // on which the iterator was created has been deleted. |
| // |
| // The iterator is initially positioned at the beginning of the table. |
| // |
| // This method is equivalent to: |
| // Iterator* iter = table->NewIterator(); |
| // iter->Seek(""); |
| // return iter; |
| // If you are going to immediately seek to another place in the |
| // returned iterator, it will be faster to use NewIterator() |
| // and avoid the extra seek. |
| Iterator* GetIterator() const; |
| </CODE_SNIPPET> |
| <p> |
| However, do not be unnecessarily verbose or state the |
| completely obvious. Notice below that it is not necessary |
| to say "returns false otherwise" because this is implied. |
| </p> |
| <CODE_SNIPPET> |
| // Returns true if the table cannot hold any more entries. |
| bool IsTableFull(); |
| </CODE_SNIPPET> |
| <p> |
| When commenting constructors and destructors, remember that |
| the person reading your code knows what constructors and |
| destructors are for, so comments that just say something like |
| "destroys this object" are not useful. Document what |
| constructors do with their arguments (for example, if they |
| take ownership of pointers), and what cleanup the destructor |
| does. If this is trivial, just skip the comment. It is |
| quite common for destructors not to have a header comment. |
| </p> |
| </SUBSECTION> |
| |
| <SUBSECTION title="Function Definitions"> |
| <p> |
| Each function definition should have a comment describing |
| what the function does if there's anything tricky about how it does |
| its job. For example, in the definition comment you might |
| describe any coding tricks you use, give an overview of the |
| steps you go through, or explain why you chose to implement |
| the function in the way you did rather than using a viable |
| alternative. For instance, you might mention why it must |
| acquire a lock for the first half of the function but why it |
| is not needed for the second half. |
| </p> |
| <p> |
| Note you should <em>not</em> just repeat the comments given |
| with the function declaration, in the <code>.h</code> file or |
| wherever. It's okay to recapitulate briefly what the function |
| does, but the focus of the comments should be on how it does it. |
| </p> |
| </SUBSECTION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Variable Comments"> |
| <SUMMARY> |
| In general the actual name of the variable should be descriptive |
| enough to give a good idea of what the variable is used for. In |
| certain cases, more comments are required. |
| </SUMMARY> |
| <BODY> |
| <SUBSECTION title="Class Data Members"> |
| <p> |
| Each class data member (also called an instance variable or |
| member variable) should have a comment describing what it is |
| used for. If the variable can take sentinel values with |
| special meanings, such as a null pointer or -1, document this. |
| For example: |
| </p> |
| <CODE_SNIPPET> |
| private: |
| // Keeps track of the total number of entries in the table. |
| // Used to ensure we do not go over the limit. -1 means |
| // that we don't yet know how many entries the table has. |
| int num_total_entries_; |
| </CODE_SNIPPET> |
| </SUBSECTION> |
| |
| <SUBSECTION title="Global Variables"> |
| <p> |
| As with data members, all global variables should have a |
| comment describing what they are and what they are used for. |
| For example: |
| </p> |
| <CODE_SNIPPET> |
| // The total number of tests cases that we run through in this regression test. |
| const int kNumTestCases = 6; |
| </CODE_SNIPPET> |
| </SUBSECTION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Implementation Comments"> |
| <SUMMARY> |
| In your implementation you should have comments in tricky, |
| non-obvious, interesting, or important parts of your code. |
| </SUMMARY> |
| <BODY> |
| <SUBSECTION title="Class Data Members"> |
| <p> |
| Tricky or complicated code blocks should have comments |
| before them. Example: |
| </p> |
| <CODE_SNIPPET> |
| // Divide result by two, taking into account that x |
| // contains the carry from the add. |
| for (int i = 0; i < result->size(); i++) { |
| x = (x << 8) + (*result)[i]; |
| (*result)[i] = x >> 1; |
| x &= 1; |
| } |
| </CODE_SNIPPET> |
| </SUBSECTION> |
| <SUBSECTION title="Line Comments"> |
| <p> |
| Also, lines that are non-obvious should get a comment at the |
| end of the line. These end-of-line comments should be |
| separated from the code by 2 spaces. Example: |
| </p> |
| <CODE_SNIPPET> |
| // If we have enough memory, mmap the data portion too. |
| mmap_budget = max<int64>(0, mmap_budget - index_->length()); |
| if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock)) |
| return; // Error already logged. |
| </CODE_SNIPPET> |
| <p> |
| Note that there are both comments that describe what the |
| code is doing, and comments that mention that an error has |
| already been logged when the function returns. |
| </p> |
| <p> |
| If you have several comments on subsequent lines, it can |
| often be more readable to line them up: |
| </p> |
| <CODE_SNIPPET> |
| DoSomething(); // Comment here so the comments line up. |
| DoSomethingElseThatIsLonger(); // Comment here so there are two spaces between |
| // the code and the comment. |
| { // One space before comment when opening a new scope is allowed, |
| // thus the comment lines up with the following comments and code. |
| DoSomethingElse(); // Two spaces before line comments normally. |
| } |
| </CODE_SNIPPET> |
| </SUBSECTION> |
| <SUBSECTION title="nullptr/NULL, true/false, 1, 2, 3..."> |
| <p> |
| When you pass in a null pointer, boolean, or literal integer |
| values to functions, you should consider adding a comment about |
| what they are, or make your code self-documenting by using |
| constants. For example, compare: |
| </p> |
| <BAD_CODE_SNIPPET> |
| bool success = CalculateSomething(interesting_value, |
| 10, |
| false, |
| NULL); // What are these arguments?? |
| </BAD_CODE_SNIPPET> |
| <p> |
| versus: |
| </p> |
| <CODE_SNIPPET> |
| bool success = CalculateSomething(interesting_value, |
| 10, // Default base value. |
| false, // Not the first time we're calling this. |
| NULL); // No callback. |
| </CODE_SNIPPET> |
| <p> |
| Or alternatively, constants or self-describing variables: |
| </p> |
| <CODE_SNIPPET> |
| const int kDefaultBaseValue = 10; |
| const bool kFirstTimeCalling = false; |
| Callback *null_callback = NULL; |
| bool success = CalculateSomething(interesting_value, |
| kDefaultBaseValue, |
| kFirstTimeCalling, |
| null_callback); |
| </CODE_SNIPPET> |
| </SUBSECTION> |
| |
| <SUBSECTION title="Don'ts"> |
| <p> |
| Note that you should <em>never</em> describe the code |
| itself. Assume that the person reading the code knows C++ |
| better than you do, even though he or she does not know what |
| you are trying to do: |
| </p> |
| <BAD_CODE_SNIPPET> |
| // Now go through the b array and make sure that if i occurs, |
| // the next element is i+1. |
| ... // Geez. What a useless comment. |
| </BAD_CODE_SNIPPET> |
| </SUBSECTION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Punctuation, Spelling and Grammar"> |
| <SUMMARY> |
| Pay attention to punctuation, spelling, and grammar; it is |
| easier to read well-written comments than badly written ones. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Comments should be as readable as narrative text, with proper |
| capitalization and punctuation. In many cases, complete sentences are |
| more readable than sentence fragments. Shorter comments, such as |
| comments at the end of a line of code, can sometimes be less formal, but |
| you should be consistent with your style. |
| </p> |
| <p> |
| Although it can be frustrating to have a code reviewer point |
| out that you are using a comma when you should be using a |
| semicolon, it is very important that source code maintain a |
| high level of clarity and readability. Proper punctuation, |
| spelling, and grammar help with that goal. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="TODO Comments"> |
| <SUMMARY> |
| Use <code>TODO</code> comments for code that is temporary, a |
| short-term solution, or good-enough but not perfect. |
| </SUMMARY> |
| <BODY> |
| <p> |
| <code>TODO</code>s should include the string <code>TODO</code> in |
| all caps, followed by the |
| |
| name, e-mail address, or other |
| identifier |
| of the person who can best provide context about the problem |
| referenced by the <code>TODO</code>. A colon is optional. The main |
| purpose is to have a consistent <code>TODO</code> format that can be |
| searched to find the person who can provide more details upon request. |
| A <code>TODO</code> is not a commitment that the person referenced |
| will fix the problem. Thus when you create a <code>TODO</code>, it is |
| almost always your |
| |
| name |
| that is given. |
| </p> |
| |
| <CODE_SNIPPET> |
| // TODO(kl@gmail.com): Use a "*" here for concatenation operator. |
| // TODO(Zeke) change this to use relations. |
| </CODE_SNIPPET> |
| <p> |
| If your <code>TODO</code> is of the form "At a future date do |
| something" make sure that you either include a very specific |
| date ("Fix by November 2005") or a very specific event |
| ("Remove this code when all clients can handle XML responses."). |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Deprecation Comments"> |
| <SUMMARY> |
| Mark deprecated interface points with <code>DEPRECATED</code> comments. |
| </SUMMARY> |
| <BODY> |
| <p> |
| You can mark an interface as deprecated by writing a comment containing |
| the word <code>DEPRECATED</code> in all caps. The comment goes either |
| before the declaration of the interface or on the same line as the |
| declaration. |
| </p> |
| |
| <p> |
| After the word <code>DEPRECATED</code>, write your name, e-mail address, |
| or other identifier in parentheses. |
| </p> |
| <p> |
| A deprecation comment must include simple, clear directions for people to |
| fix their callsites. In C++, you can implement a deprecated function as |
| an inline function that calls the new interface point. |
| </p> |
| <p> |
| Marking an interface point <code>DEPRECATED</code> will not magically |
| cause any callsites to change. If you want people to actually stop using |
| the deprecated facility, you will have to fix the callsites yourself or |
| recruit a crew to help you. |
| </p> |
| <p> |
| New code should not contain calls to deprecated interface points. Use |
| the new interface point instead. If you cannot understand the |
| directions, find the person who created the deprecation and ask them for |
| help using the new interface point. |
| </p> |
| |
| </BODY> |
| </STYLEPOINT> |
| |
| </CATEGORY> |
| |
| <CATEGORY title="Formatting"> |
| <p> |
| Coding style and formatting are pretty arbitrary, but a |
| |
| project |
| is much easier to follow if everyone uses the same style. Individuals |
| may not agree with every aspect of the formatting rules, and some of |
| the rules may take some getting used to, but it is important that all |
| |
| project contributors |
| follow the style rules so that |
| |
| they |
| can all read and understand everyone's code easily. |
| </p> |
| |
| <p> |
| To help you format code correctly, we've created a <A HREF="http://google-styleguide.googlecode.com/svn/trunk/google-c-style.el">settings |
| file for emacs</A>. |
| </p> |
| |
| <STYLEPOINT title="Line Length"> |
| <SUMMARY> |
| Each line of text in your code should be at most 80 characters |
| long. |
| </SUMMARY> |
| <BODY> |
| |
| <p> |
| We recognize that this rule is controversial, but so much existing |
| code already adheres to it, and we feel that consistency is |
| important. |
| </p> |
| <PROS> |
| Those who favor |
| |
| this rule argue |
| that it is rude to force them to resize their windows and there |
| is no need for anything longer. Some folks are used to having |
| several code windows side-by-side, and thus don't have room to |
| widen their windows in any case. People set up their work |
| environment assuming a particular maximum window width, and 80 |
| columns has been the traditional standard. Why change it? |
| </PROS> |
| <CONS> |
| Proponents of change argue that a wider line can make code |
| more readable. The 80-column limit is an hidebound |
| throwback to 1960s mainframes; |
| |
| modern equipment has |
| wide screens that can easily show longer lines. |
| </CONS> |
| <DECISION> |
| <p> |
| |
| 80 characters is the maximum. |
| </p> |
| <p> |
| Exception: if a comment line contains an example command or |
| a literal URL longer than 80 characters, that line may be |
| longer than 80 characters for ease of cut and paste. |
| </p> |
| <p> |
| Exception: an <code>#include</code> statement with a long |
| path may exceed 80 columns. Try to avoid situations where this |
| becomes necessary. |
| </p> |
| <p> |
| Exception: you needn't be concerned about |
| <a href="#The__define_Guard">header guards</a> |
| that exceed the maximum length. |
| |
| </p> |
| </DECISION> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Non-ASCII Characters"> |
| <SUMMARY> |
| Non-ASCII characters should be rare, and must use UTF-8 formatting. |
| </SUMMARY> |
| <BODY> |
| <p> |
| You shouldn't hard-code user-facing text in source, even English, |
| so use of non-ASCII characters should be rare. However, in certain |
| cases it is appropriate to include such words in your code. For |
| example, if your code parses data files from foreign sources, |
| it may be appropriate to hard-code the non-ASCII string(s) used in |
| those data files as delimiters. More commonly, unittest code |
| (which does not |
| |
| need to be localized) might contain non-ASCII strings. In such |
| cases, you should use UTF-8, since that is |
| |
| an encoding understood by most tools able |
| to handle more than just ASCII. |
| Hex encoding is also OK, and encouraged where it enhances |
| readability — for example, <code>"\xEF\xBB\xBF"</code> is the |
| Unicode zero-width no-break space character, which would be |
| invisible if included in the source as straight UTF-8. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Spaces vs. Tabs"> |
| <SUMMARY> |
| Use only spaces, and indent 2 spaces at a time. |
| </SUMMARY> |
| <BODY> |
| <p> |
| We use spaces for indentation. Do not use tabs in your code. |
| You should set your editor to emit spaces when you hit the tab |
| key. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Function Declarations and Definitions"> |
| <SUMMARY> |
| Return type on the same line as function name, parameters on the |
| same line if they fit. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Functions look like this: |
| </p> |
| <CODE_SNIPPET> |
| ReturnType ClassName::FunctionName(Type par_name1, Type par_name2) { |
| DoSomething(); |
| ... |
| } |
| </CODE_SNIPPET> |
| <p> |
| If you have too much text to fit on one line: |
| </p> |
| <CODE_SNIPPET> |
| ReturnType ClassName::ReallyLongFunctionName(Type par_name1, Type par_name2, |
| Type par_name3) { |
| DoSomething(); |
| ... |
| } |
| </CODE_SNIPPET> |
| <p> |
| or if you cannot fit even the first parameter: |
| </p> |
| <CODE_SNIPPET> |
| ReturnType LongClassName::ReallyReallyReallyLongFunctionName( |
| Type par_name1, // 4 space indent |
| Type par_name2, |
| Type par_name3) { |
| DoSomething(); // 2 space indent |
| ... |
| } |
| </CODE_SNIPPET> |
| <p> |
| Some points to note: |
| </p> |
| <ul> |
| <li> The return type is always on the same line as the |
| function name. |
| </li> |
| <li> The open parenthesis is always on the same line as the |
| function name. |
| </li> |
| <li> There is never a space between the function name and the |
| open parenthesis. |
| </li> |
| <li> There is never a space between the parentheses and the |
| parameters. |
| </li> |
| <li> The open curly brace is always at the end of the same |
| line as the last parameter. |
| </li> |
| <li> The close curly brace is either on the last line by itself |
| or (if other style rules permit) on the same line as the |
| open curly brace. |
| </li> |
| <li> There should be a space between the close parenthesis and |
| the open curly brace. |
| </li> |
| <li> All parameters should be named, with identical names in the |
| declaration and implementation. |
| </li> |
| <li> All parameters should be aligned if possible. |
| </li> |
| <li> Default indentation is 2 spaces. |
| </li> |
| <li> Wrapped parameters have a 4 space indent. |
| </li> |
| </ul> |
| <p> |
| If some parameters are unused, comment out the variable name in the |
| function definition: |
| </p> |
| <CODE_SNIPPET> |
| // Always have named parameters in interfaces. |
| class Shape { |
| public: |
| virtual void Rotate(double radians) = 0; |
| } |
| |
| // Always have named parameters in the declaration. |
| class Circle : public Shape { |
| public: |
| virtual void Rotate(double radians); |
| } |
| |
| // Comment out unused named parameters in definitions. |
| void Circle::Rotate(double /*radians*/) {} |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| // Bad - if someone wants to implement later, it's not clear what the |
| // variable means. |
| void Circle::Rotate(double) {} |
| </BAD_CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Function Calls"> |
| <SUMMARY> |
| On one line if it fits; otherwise, wrap arguments at the |
| parenthesis. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Function calls have the following format: |
| </p> |
| <CODE_SNIPPET> |
| bool retval = DoSomething(argument1, argument2, argument3); |
| </CODE_SNIPPET> |
| <p> |
| If the arguments do not all fit on one line, they should be |
| broken up onto multiple lines, with each subsequent line |
| aligned with the first argument. Do not add spaces after the |
| open paren or before the close paren: |
| </p> |
| <CODE_SNIPPET> |
| bool retval = DoSomething(averyveryveryverylongargument1, |
| argument2, argument3); |
| </CODE_SNIPPET> |
| <p> |
| If the function has many arguments, consider having one per |
| line if this makes the code more readable: |
| </p> |
| <CODE_SNIPPET> |
| bool retval = DoSomething(argument1, |
| argument2, |
| argument3, |
| argument4); |
| </CODE_SNIPPET> |
| <p> |
| Arguments may optionally all be placed on subsequent lines, with one |
| line per argument: |
| </p> |
| <CODE_SNIPPET> |
| if (...) { |
| ... |
| ... |
| if (...) { |
| DoSomething( |
| argument1, // 4 space indent |
| argument2, |
| argument3, |
| argument4); |
| } |
| </CODE_SNIPPET> |
| <p> |
| In particular, this should be done if the function signature is so long |
| that it cannot fit within the maximum <a href="#Line_Length">line |
| length</a>. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Conditionals"> |
| <SUMMARY> |
| Prefer no spaces inside parentheses. The <code>else</code> |
| keyword belongs on a new line. |
| </SUMMARY> |
| <BODY> |
| <p> |
| There are two acceptable formats for a basic conditional |
| statement. One includes spaces between the parentheses and the |
| condition, and one does not. |
| </p> |
| <p> |
| The most common form is without spaces. Either is fine, but |
| <em>be consistent</em>. If you are modifying a file, use the |
| format that is already present. If you are writing new code, |
| use the format that the other files in that directory or |
| project use. If in doubt and you have no personal preference, |
| do not add the spaces. |
| </p> |
| <CODE_SNIPPET> |
| if (condition) { // no spaces inside parentheses |
| ... // 2 space indent. |
| } else if (...) { // The else goes on the same line as the closing brace. |
| ... |
| } else { |
| ... |
| } |
| </CODE_SNIPPET> |
| <p> |
| If you prefer you may add spaces inside the |
| parentheses: |
| </p> |
| <CODE_SNIPPET> |
| if ( condition ) { // spaces inside parentheses - rare |
| ... // 2 space indent. |
| } else { // The else goes on the same line as the closing brace. |
| ... |
| } |
| </CODE_SNIPPET> |
| <p> |
| Note that in all cases you must have a space between the |
| <code>if</code> and the open parenthesis. You must also have |
| a space between the close parenthesis and the curly brace, if |
| you're using one. |
| </p> |
| <BAD_CODE_SNIPPET> |
| if(condition) // Bad - space missing after IF. |
| if (condition){ // Bad - space missing before {. |
| if(condition){ // Doubly bad. |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| if (condition) { // Good - proper space after IF and before {. |
| </CODE_SNIPPET> |
| <p> |
| Short conditional statements may be written on one line if |
| this enhances readability. You may use this only when the |
| line is brief and the statement does not use the |
| <code>else</code> clause. |
| </p> |
| <CODE_SNIPPET> |
| if (x == kFoo) return new Foo(); |
| if (x == kBar) return new Bar(); |
| </CODE_SNIPPET> |
| <p> |
| This is not allowed when the if statement has an |
| <code>else</code>: |
| </p> |
| <BAD_CODE_SNIPPET> |
| // Not allowed - IF statement on one line when there is an ELSE clause |
| if (x) DoThis(); |
| else DoThat(); |
| </BAD_CODE_SNIPPET> |
| <p> |
| In general, curly braces are not required for single-line |
| statements, but they are allowed if you like them; |
| conditional or loop statements with complex conditions or |
| statements may be more readable with curly braces. Some |
| |
| projects |
| require that an <CODE>if</CODE> must always always have an |
| accompanying brace. |
| </p> |
| <CODE_SNIPPET> |
| if (condition) |
| DoSomething(); // 2 space indent. |
| |
| if (condition) { |
| DoSomething(); // 2 space indent. |
| } |
| </CODE_SNIPPET> |
| <p> |
| However, if one part of an <code>if</code>-<code>else</code> |
| statement uses curly braces, the other part must too: |
| </p> |
| <BAD_CODE_SNIPPET> |
| // Not allowed - curly on IF but not ELSE |
| if (condition) { |
| foo; |
| } else |
| bar; |
| |
| // Not allowed - curly on ELSE but not IF |
| if (condition) |
| foo; |
| else { |
| bar; |
| } |
| </BAD_CODE_SNIPPET> |
| <CODE_SNIPPET> |
| // Curly braces around both IF and ELSE required because |
| // one of the clauses used braces. |
| if (condition) { |
| foo; |
| } else { |
| bar; |
| } |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Loops and Switch Statements"> |
| <SUMMARY> |
| Switch statements may use braces for blocks. Annotate non-trivial |
| fall-through between cases. Empty loop bodies should use <code>{}</code> |
| or <code>continue</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| <code>case</code> blocks in <code>switch</code> statements can have |
| curly braces or not, depending on your preference. If you do |
| include curly braces they should be placed as shown below. |
| </p> |
| <p> |
| If not conditional on an enumerated value, switch statements |
| should always have a <code>default</code> case (in the case of |
| an enumerated value, the compiler will warn you if any values |
| are not handled). If the default case should never execute, |
| simply |
| <code>assert</code>: |
| </p> |
| |
| <CODE_SNIPPET> |
| switch (var) { |
| case 0: { // 2 space indent |
| ... // 4 space indent |
| break; |
| } |
| case 1: { |
| ... |
| break; |
| } |
| default: { |
| assert(false); |
| } |
| } |
| </CODE_SNIPPET> |
| |
| |
| <p> |
| Empty loop bodies should use <code>{}</code> or |
| <code>continue</code>, but not a single semicolon. |
| </p> |
| <CODE_SNIPPET> |
| while (condition) { |
| // Repeat test until it returns false. |
| } |
| for (int i = 0; i < kSomeNumber; ++i) {} // Good - empty body. |
| while (condition) continue; // Good - continue indicates no logic. |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| while (condition); // Bad - looks like part of do/while loop. |
| </BAD_CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Pointer and Reference Expressions"> |
| <SUMMARY> |
| No spaces around period or arrow. Pointer operators do not have |
| trailing spaces. |
| </SUMMARY> |
| <BODY> |
| <p> |
| The following are examples of correctly-formatted pointer and |
| reference expressions: |
| </p> |
| <CODE_SNIPPET> |
| x = *p; |
| p = &x; |
| x = r.y; |
| x = r->y; |
| </CODE_SNIPPET> |
| <p> |
| Note that: |
| </p> |
| <ul> |
| <li> There are no spaces around the period or arrow when |
| accessing a member. |
| </li> |
| <li> Pointer operators have no space after the <code>*</code> or |
| <code>&</code>. |
| </li> |
| </ul> |
| <p> |
| When declaring a pointer variable or argument, you may place |
| the asterisk adjacent to either the type or to the variable |
| name: |
| </p> |
| <CODE_SNIPPET> |
| // These are fine, space preceding. |
| char *c; |
| const string &str; |
| |
| // These are fine, space following. |
| char* c; // but remember to do "char* c, *d, *e, ...;"! |
| const string& str; |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| char * c; // Bad - spaces on both sides of * |
| const string & str; // Bad - spaces on both sides of & |
| </BAD_CODE_SNIPPET> |
| <p> |
| You should do this consistently within a single |
| file, |
| so, when modifying an existing file, use the style in that |
| file. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Boolean Expressions"> |
| <SUMMARY> |
| When you have a boolean expression that is longer than the <a href="#Line_Length">standard line length</a>, be consistent in |
| how you break up the lines. |
| </SUMMARY> |
| <BODY> |
| <p> |
| In this example, the logical AND operator is always at the end |
| of the lines: |
| </p> |
| <CODE_SNIPPET> |
| if (this_one_thing > this_other_thing && |
| a_third_thing == a_fourth_thing && |
| yet_another && last_one) { |
| ... |
| } |
| </CODE_SNIPPET> |
| <p> |
| Note that when the code wraps in this example, both of |
| the <code>&&</code> logical AND operators are at the |
| end of the line. This is more common in Google code, though |
| wrapping all operators at the beginning of the line is also |
| allowed. Feel free to insert extra parentheses judiciously |
| because they can be very helpful in increasing readability |
| when used appropriately. Also note that you should always use the |
| punctuation operators, such as <code>&&</code> and |
| <code>~</code>, rather than the word operators, such as <code>and</code> |
| and <code>compl</code>. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Return Values"> |
| <SUMMARY> |
| Do not needlessly surround the <code>return</code> expression with |
| parentheses. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Use parentheses in <code>return expr;</code> only where you would use |
| them in <code>x = expr;</code>. |
| </p> |
| <CODE_SNIPPET> |
| return result; // No parentheses in the simple case. |
| return (some_long_condition && // Parentheses ok to make a complex |
| another_condition); // expression more readable. |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| return (value); // You wouldn't write var = (value); |
| return(result); // return is not a function! |
| </BAD_CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| |
| |
| <STYLEPOINT title="Variable and Array Initialization"> |
| <SUMMARY> |
| Your choice of <code>=</code> or <code>()</code>. |
| </SUMMARY> |
| <BODY> |
| <p> |
| You may choose between <code>=</code> and <code>()</code>; the |
| following are all correct: |
| </p> |
| <CODE_SNIPPET> |
| int x = 3; |
| int x(3); |
| string name("Some Name"); |
| string name = "Some Name"; |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Preprocessor Directives"> |
| <SUMMARY> |
| The hash mark that starts a preprocessor directive should |
| always be at the beginning of the line. |
| </SUMMARY> |
| <BODY> |
| <p> |
| Even when preprocessor directives are within the body of |
| indented code, the directives should start at the beginning of |
| the line. |
| </p> |
| <CODE_SNIPPET> |
| // Good - directives at beginning of line |
| if (lopsided_score) { |
| #if DISASTER_PENDING // Correct -- Starts at beginning of line |
| DropEverything(); |
| # if NOTIFY // OK but not required -- Spaces after # |
| NotifyClient(); |
| # endif |
| #endif |
| BackToNormal(); |
| } |
| </CODE_SNIPPET> |
| <BAD_CODE_SNIPPET> |
| // Bad - indented directives |
| if (lopsided_score) { |
| #if DISASTER_PENDING // Wrong! The "#if" should be at beginning of line |
| DropEverything(); |
| #endif // Wrong! Do not indent "#endif" |
| BackToNormal(); |
| } |
| </BAD_CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Class Format"> |
| <SUMMARY> |
| Sections in <code>public</code>, <code>protected</code> and |
| <code>private</code> order, each indented one space. |
| </SUMMARY> |
| <BODY> |
| <p> |
| The basic format for a class declaration (lacking the |
| comments, see <a HREF="#Class_Comments">Class Comments</a> for |
| a discussion of what comments are needed) is: |
| </p> |
| <CODE_SNIPPET> |
| class MyClass : public OtherClass { |
| public: // Note the 1 space indent! |
| MyClass(); // Regular 2 space indent. |
| explicit MyClass(int var); |
| ~MyClass() {} |
| |
| void SomeFunction(); |
| void SomeFunctionThatDoesNothing() { |
| } |
| |
| void set_some_var(int var) { some_var_ = var; } |
| int some_var() const { return some_var_; } |
| |
| private: |
| bool SomeInternalFunction(); |
| |
| int some_var_; |
| int some_other_var_; |
| DISALLOW_COPY_AND_ASSIGN(MyClass); |
| }; |
| </CODE_SNIPPET> |
| <p> |
| Things to note: |
| </p> |
| <ul> |
| <li> Any base class name should be on the same line as the |
| subclass name, subject to the 80-column limit. |
| </li> |
| <li> The <code>public:</code>, <code>protected:</code>, and |
| <code>private:</code> keywords should be indented one |
| space. |
| </li> |
| <li> Except for the first instance, these keywords should be preceded |
| by a blank line. This rule is optional in small classes. |
| </li> |
| <li> Do not leave a blank line after these keywords. |
| </li> |
| <li> The <code>public</code> section should be first, followed by |
| the <code>protected</code> and finally the |
| <code>private</code> section. |
| </li> |
| <li> See <a HREF="#Declaration_Order">Declaration Order</a> for |
| rules on ordering declarations within each of these sections. |
| </li> |
| </ul> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Constructor Initializer Lists"> |
| <SUMMARY> |
| Constructor initializer lists can be all on one line or with |
| subsequent lines indented four spaces. |
| </SUMMARY> |
| <BODY> |
| <p> |
| There are two acceptable formats for initializer lists: |
| </p> |
| <CODE_SNIPPET> |
| // When it all fits on one line: |
| MyClass::MyClass(int var) : some_var_(var), some_other_var_(var + 1) {} |
| </CODE_SNIPPET> |
| <p> |
| or |
| </p> |
| <CODE_SNIPPET> |
| // When it requires multiple lines, indent 4 spaces, putting the colon on |
| // the first initializer line: |
| MyClass::MyClass(int var) |
| : some_var_(var), // 4 space indent |
| some_other_var_(var + 1) { // lined up |
| ... |
| DoSomething(); |
| ... |
| } |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Namespace Formatting"> |
| <SUMMARY> |
| The contents of namespaces are not indented. |
| </SUMMARY> |
| <BODY> |
| <p> |
| <a href="#Namespaces">Namespaces</a> do not add an extra level of |
| indentation. For example, use: |
| </p> |
| <CODE_SNIPPET> |
| namespace { |
| |
| void foo() { // Correct. No extra indentation within namespace. |
| ... |
| } |
| |
| } // namespace |
| </CODE_SNIPPET> |
| <p> |
| Do not indent within a namespace: |
| </p> |
| <BAD_CODE_SNIPPET> |
| namespace { |
| |
| // Wrong. Indented when it should not be. |
| void foo() { |
| ... |
| } |
| |
| } // namespace |
| </BAD_CODE_SNIPPET> |
| <p> |
| When declaring nested namespaces, put each namespace on its own line. |
| </p> |
| <CODE_SNIPPET> |
| namespace foo { |
| namespace bar { |
| </CODE_SNIPPET> |
| </BODY> |
| </STYLEPOINT> |
| |
| <STYLEPOINT title="Horizontal Whitespace"> |
| <SUMMARY> |
| Use of horizontal whitespace depends on location. Never put trailing |
| whitespace at the end of a line. |
| </SUMMARY> |
| <BODY> |
| <SUBSECTION title="General"> |
| <CODE_SNIPPET> |
| void f(bool b) { // Open braces should always have a space before them. |
| ... |
| int i = 0; // Semicolons usually have no space before them. |
| int x[] = { 0 }; // Spaces inside braces for array initialization are |
| int x[] = {0}; // optional. If you use them, put them on both sides! |
| // Spaces around the colon in inheritance and initializer lists. |
| class Foo : public Bar { |
| public: |
| // For inline function implementations, put spaces between the braces |
| // and the implementation itself. |
| Foo(int b) : Bar(), baz_(b) {} // No spaces inside empty braces. |
| void Reset() { baz_ = 0; } // Spaces separating braces from implementation. |
| ... |
| </CODE_SNIPPET> |
| <p> |
| Adding trailing whitespace can cause extra work for others editing |
| the same file, when they merge, as can removing existing trailing |
| whitespace. So: Don't introduce trailing whitespace. Remove it |
| if you're already changing that line, or do it in a separate |
| clean-up |
| |
| operation (preferably when no-one else |
| is working on the file). |
| </p> |
| </SUBSECTION> |
| <SUBSECTION title="Loops and Conditionals"> |
| <CODE_SNIPPET> |
| if (b) { // Space after the keyword in conditions and loops. |
| } else { // Spaces around else. |
| } |
| while (test) {} // There is usually no space inside parentheses. |
| switch (i) { |
| for (int i = 0; i < 5; ++i) { |
| switch ( i ) { // Loops and conditions may have spaces inside |
| if ( test ) { // parentheses, but this is rare. Be consistent. |
| for ( int i = 0; i < 5; ++i ) { |
| for ( ; i < 5 ; ++i) { // For loops always have a space after the |
| ... // semicolon, and may have a space before the |
| // semicolon. |
| for (auto x : counts) { // Range-based for loops always have a |
| ... // space before and after the colon. |
| } |
| switch (i) { |
| case 1: // No space before colon in a switch case. |
| ... |
| case 2: break; // Use a space after a colon if there's code after it. |
| </CODE_SNIPPET> |
| </SUBSECTION> |
| <SUBSECTION title="Operators"> |
| <CODE_SNIPPET> |
| x = 0; // Assignment operators always have spaces around |
| // them. |
| x = -5; // No spaces separating unary operators and their |
| ++x; // arguments. |
| if (x && !y) |
| ... |
| v = w * x + y / z; // Binary operators usually have spaces around them, |
| v = w*x + y/z; // but it's okay to remove spaces around factors. |
| v = w * (x + z); // Parentheses should have no spaces inside them. |
| </CODE_SNIPPET> |
| </SUBSECTION> |
| <SUBSECTION title="Templates and Casts"> |
| <CODE_SNIPPET> |
| vector<string> x; // No spaces inside the angle |
| y = static_cast<char*>(x); // brackets (< and >), before |
| // <, or between >( in a cast. |
| vector<char *> x; // Spaces between type and pointer are |
| // okay, but be consistent. |
| set<list<string>> x; // Permitted in C++11 code. |
| set<list<string> > x; // C++03 required a space in > >. |
| set< list<string> > x; // You may optionally use |
| // symmetric spacing in < <. |
| </CODE_SNIPPET> |
| </SUBSECTION> |
| </BODY> |
| </STYLEPOINT> |
| |
| |
| <STYLEPOINT title="Vertical Whitespace"> |
| <SUMMARY> |
| Minimize use of vertical whitespace. |
| </SUMMARY> |
| <BODY> |
| <p> |
| This is more a principle than a rule: don't use blank lines |
| when you don't have to. In particular, don't put more than |
| one or two blank lines between functions, resist starting |
| functions with a blank line, don't end functions with a blank |
| line, and be discriminating with your use of blank lines |
| inside functions. |
| </p> |
| <p> |
| The basic principle is: The more code that fits on one screen, |
| the easier it is to follow and understand the control flow of |
| the program. Of course, readability can suffer from code |
| being too dense as well as too spread out, so use your |
| judgement. But in general, minimize use of vertical |
| whitespace. |
| </p> |
| <p> |
| Some rules of thumb to help when blank lines may be useful: |
| </p> |
| <ul> |
| <li> Blank lines at the beginning or end of a function very |
| rarely help readability. |
| </li> |
| <li> Blank lines inside a chain of if-else blocks may well |
| help readability. |
| </li> |
| </ul> |
| </BODY> |
| </STYLEPOINT> |
| </CATEGORY> |
| |
| <CATEGORY title="Exceptions to the Rules"> |
| <p> |
| The coding conventions described above are mandatory. However, |
| like all good rules, these sometimes have exceptions, which we |
| discuss here. |
| </p> |
| |
| |
| |
| <STYLEPOINT title="Existing Non-conformant Code"> |
| <SUMMARY> |
| You may diverge from the rules when dealing with code that does not |
| conform to this style guide. |
| </SUMMARY> |
| <BODY> |
| <p> |
| If you find yourself modifying code that was written to |
| specifications other than those presented by this guide, you may |
| have to diverge from these rules in order to stay consistent with |
| the local conventions in that code. If you are in doubt about |
| how to do this, ask the original author or the person currently |
| responsible for the code. Remember that <em>consistency</em> |
| includes local consistency, too. |
| </p> |
| </BODY> |
| </STYLEPOINT> |
| |
| |
| |
| <STYLEPOINT title="Windows Code"> |
| <SUMMARY> |
| |
| Windows programmers have developed their own set of coding |
| conventions, mainly derived from the conventions in Windows headers |
| and other Microsoft code. We want to make it easy for anyone to |
| understand your code, so we have a single set of guidelines for |
| everyone writing C++ on any platform. |
| </SUMMARY> |
| <BODY> |
| <p> |
| It is worth reiterating a few of the guidelines that you might |
| forget if you are used to the prevalent Windows style: |
| </p> |
| <ul> |
| <li> Do not use Hungarian notation (for example, naming an |
| integer <code>iNum</code>). Use the Google naming conventions, |
| including the <code>.cc</code> extension for source files. |
| </li> |
| <li> Windows defines many of its own synonyms for primitive |
| types, such as <code>DWORD</code>, <code>HANDLE</code>, etc. |
| It is perfectly acceptable, and encouraged, that you use these |
| types when calling Windows API functions. Even so, keep as |
| close as you can to the underlying C++ types. For example, use |
| <code>const TCHAR *</code> instead of <code>LPCTSTR</code>. |
| </li> |
| <li> When compiling with Microsoft Visual C++, set the |
| compiler to warning level 3 or higher, and treat all |
| warnings as errors. |
| </li> |
| <li> Do not use <code>#pragma once</code>; instead use the |
| standard Google include guards. The path in the include |
| guards should be relative to the top of your project |
| tree. |
| </li> |
| <li> In fact, do not use any nonstandard extensions, like |
| <code>#pragma</code> and <code>__declspec</code>, unless you |
| absolutely must. Using <code>__declspec(dllimport)</code> and |
| <code>__declspec(dllexport)</code> is allowed; however, you |
| must use them through macros such as <code>DLLIMPORT</code> |
| and <code>DLLEXPORT</code>, so that someone can easily disable |
| the extensions if they share the code. |
| </li> |
| </ul> |
| <p> |
| However, there are just a few rules that we occasionally need |
| to break on Windows: |
| </p> |
| <ul> |
| <li> Normally we <a HREF="#Multiple_Inheritance">forbid |
| the use of multiple implementation inheritance</a>; however, |
| it is required when using COM and some ATL/WTL |
| classes. You may use multiple implementation inheritance |
| to implement COM or ATL/WTL classes and interfaces. |
| </li> |
| <li> Although you should not use exceptions in your own code, |
| they are used extensively in the ATL and some STLs, |
| including the one that comes with Visual C++. When using |
| the ATL, you should define <code>_ATL_NO_EXCEPTIONS</code> to |
| disable exceptions. You should investigate whether you can |
| also disable exceptions in your STL, but if not, it is OK to |
| turn on exceptions in the compiler. (Note that this is |
| only to get the STL to compile. You should still not |
| write exception handling code yourself.) |
| </li> |
| <li> The usual way of working with precompiled headers is to |
| include a header file at the top of each source file, |
| typically with a name like <code>StdAfx.h</code> or |
| <code>precompile.h</code>. To make your code easier to share |
| with other projects, avoid including this file explicitly |
| (except in <code>precompile.cc</code>), and use the |
| <code>/FI</code> compiler option to include the file |
| automatically. |
| </li> |
| <li> Resource headers, which are usually named |
| <code>resource.h</code> and contain only macros, do not need |
| to conform to these style guidelines. |
| </li> |
| </ul> |
| </BODY> |
| </STYLEPOINT> |
| |
| |
| </CATEGORY> |
| |
| <PARTING_WORDS> |
| <p> |
| Use common sense and <em>BE CONSISTENT</em>. |
| </p> |
| <p> |
| If you are editing code, take a few minutes to look at the |
| code around you and determine its style. If they use spaces |
| around their <code>if</code> clauses, you should, too. If |
| their comments have little boxes of stars around them, make |
| your comments have little boxes of stars around them too. |
| </p> |
| <p> |
| The point of having style guidelines is to have a common |
| vocabulary of coding so people can concentrate on what you are |
| saying, rather than on how you are saying it. We present |
| global style rules here so people know the vocabulary. But |
| local style is also important. If code you add to a file |
| looks drastically different from the existing code around it, |
| the discontinuity throws readers out of their rhythm when they |
| go to read it. Try to avoid this. |
| </p> |
| |
| <p> |
| OK, enough writing about writing code; the code itself is much |
| more interesting. Have fun! |
| </p> |
| </PARTING_WORDS> |
| |
| <HR/> |
| |
| <p align="right"> |
| Revision 3.245 |
| </p> |
| |
| |
| |
| <address> |
| Benjy Weinberger<br/> |
| Craig Silverstein<br/> |
| Gregory Eitzmann<br/> |
| Mark Mentovai<br/> |
| Tashana Landray |
| </address> |
| |
| </GUIDE> |