diff options
Diffstat (limited to 'guides')
| -rw-r--r-- | guides/CMakeLists.txt | 9 | ||||
| -rw-r--r-- | guides/cppguide.xml | 4566 | ||||
| -rw-r--r-- | guides/styleguide.css | 147 | ||||
| -rw-r--r-- | guides/styleguide.xsl | 890 |
4 files changed, 5612 insertions, 0 deletions
diff --git a/guides/CMakeLists.txt b/guides/CMakeLists.txt new file mode 100644 index 000000000..b82730d0b --- /dev/null +++ b/guides/CMakeLists.txt @@ -0,0 +1,9 @@ +PROJECT(guides) + +ADD_CUSTOM_COMMAND( + OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/cppguide.html + COMMAND xsltproc -o ${CMAKE_CURRENT_SOURCE_DIR}/cppguide.html ${CMAKE_CURRENT_SOURCE_DIR}/styleguide.xsl ${CMAKE_CURRENT_SOURCE_DIR}/cppguide.xml + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/styleguide.xsl ${CMAKE_CURRENT_SOURCE_DIR}/cppguide.xml + ) + +ADD_CUSTOM_TARGET(guides ALL DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/cppguide.html) diff --git a/guides/cppguide.xml b/guides/cppguide.xml new file mode 100644 index 000000000..a3e45c2d2 --- /dev/null +++ b/guides/cppguide.xml @@ -0,0 +1,4566 @@ +<?xml version="1.0"?> +<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?> +<GUIDE title="Google C++ Style Guide"> + +<p align="right"> + +Revision 3.188 +</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="Header File Dependencies"> + <SUMMARY> + Don't use an <code>#include</code> when a forward declaration + would suffice. + </SUMMARY> + <BODY> + <p> + When you include a header file you introduce a dependency that + will cause your code to be recompiled whenever the header file + changes. If your header file includes other header files, any + change to those files will cause any code that includes your + header to be recompiled. Therefore, we prefer to minimize + includes, particularly includes of header files in other + header files. + </p> + <p> + You can significantly reduce the number of header files you + need to include in your own header files by using forward + declarations. For example, if your header file uses the + <code>File</code> class in ways that do not require access to + the declaration of the <code>File</code> class, your header + file can just forward declare <code>class File;</code> instead + of having to <code>#include "file/base/file.h"</code>. + </p> + <p> + How can we use a class <code>Foo</code> in a header file + without access to its definition? + </p> + <ul> + <li> We can declare data members of type <code>Foo*</code> or + <code>Foo&</code>. + </li> + <li> We can declare (but not define) functions with arguments, + and/or return values, of type <code>Foo</code>. (One + exception is if an argument <code>Foo</code> + or <code>const Foo&</code> has a + non-<code>explicit</code>, one-argument constructor, + + in which case we need the full definition to support + automatic type conversion.) + </li> + <li> We can declare static data members of type + <code>Foo</code>. This is because static data members + are defined outside the class definition. + </li> + </ul> + <p> + On the other hand, you must include the header file for + <code>Foo</code> if your class subclasses <code>Foo</code> or + has a data member of type <code>Foo</code>. + </p> + <p> + Sometimes it makes sense to have pointer (or better, + <code>scoped_ptr</code>) + members instead of object members. However, this complicates code + readability and imposes a performance penalty, so avoid doing + this transformation if the only purpose is to minimize includes + in header files. + </p> + <p> + Of course, <code>.cc</code> files typically do require the + definitions of the classes they use, and usually have to + include several header files. + </p> + + <SUBSECTION title="Note:"> + If you use a symbol <code>Foo</code> in your source file, you + should bring in a definition for <code>Foo</code> yourself, + either via an #include or via a forward declaration. Do not + depend on the symbol being brought in transitively via headers + not directly included. One exception is if <code>Foo</code> + is used in <code>myfile.cc</code>, it's ok to #include (or + forward-declare) <code>Foo</code> in <code>myfile.h</code>, + instead of <code>myfile.cc</code>. + </SUBSECTION> + </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> + The preferred ordering reduces hidden dependencies. We want + every header file to be compilable on its own. The easiest + way to achieve this is to make sure that every one of them is + the first <code>.h</code> file <code>#include</code>d in some + <code>.cc</code>. + </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 it is nice to order the includes + alphabetically. + </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 spaces 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. + </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. Terminate the unnamed + namespace as shown, with a comment <code>// + namespace</code>. + </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. + </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> + In general, constructors should merely set member variables to their + initial values. Any complex initialization should go in an explicit + <code>Init()</code> method. + </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> + If your object requires non-trivial initialization, consider + having an explicit <code>Init()</code> method. In particular, + constructors should not call virtual functions, attempt to raise + errors, access potentially uninitialized global variables, etc. + </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, they 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 + <code>NULL</code> 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. + </p> + <p> + One case when you might want an input parameter to be a + <code>const</code> pointer is if you want to emphasize that the + argument is not copied, so it must exist for the lifetime of the + object; it is usually best to document this in comments as + well. STL adapters such as <code>bind2nd</code> and + <code>mem_fun</code> do not permit reference parameters, so + you must declare functions with pointer parameters in these + cases, too. + </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 + a few uncommon situations explained below. + </SUMMARY> + <BODY> + <PROS> + Often you have a function that uses lots of 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. + </PROS> + <CONS> + People often figure out how to use an + API by looking at existing code that uses it. + Default parameters are more difficult to maintain because + copy-and-paste from previous code may not reveal all the + parameters. Copy-and-pasting of code segments can cause major + problems when the default arguments are not appropriate for + the new code. + </CONS> + <DECISION> + <p> + Except as described below, we require all arguments to be + explicitly specified, to force programmers to consider the API + and the values they are passing for each argument rather than + silently accepting defaults they may not be aware of. + </p> + <p> + One 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> + We do not use Run Time Type Information (RTTI). + </SUMMARY> + <BODY> + <DEFINITION> + RTTI allows a programmer to query the C++ class of an + object at run time. + </DEFINITION> + <PROS> + <p> + It is useful in some unittests. 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. + </p> + <p> + In rare circumstances, it is useful even outside of + tests. + </p> + </PROS> + <CONS> + A query of type during run-time typically means a + design problem. If you need to know the type of an + object at runtime, that is often an indication that + you should reconsider the design of your class. + </CONS> + <DECISION> + <p> + Do not use RTTI, except in unittests. If you find yourself + in need of writing code that behaves differently based on + the class of an object, consider one of the alternatives to + querying the type. + </p> + <p> + 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. + </p> + <p> + 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. + </p> + <p> + If you think you truly cannot use those ideas, + + you may use RTTI. But think twice + about it. :-) Then think twice again. + Do not hand-implement an RTTI-like workaround. The arguments + against RTTI apply just as much to workarounds like class + hierarchies with type tags. + </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> + <li> Do not use <code>dynamic_cast</code> except in test code. + If you need to know type information at runtime in this way + outside of a unittest, you probably have a <A HREF="#Run-Time_Type_Information__RTTI_">design + flaw</A>. + </li> + </ul> + </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> + We strongly recommend that you use <code>const</code> whenever + it makes sense to do so. + </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> + However, do not go crazy with <code>const</code>. Something like + <code>const int * const * const x;</code> is likely + overkill, even if it accurately describes how const x is. + Focus on what's really useful to know: in this case, + <code>const int** x</code> is probably sufficient. + </p> + <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 this case, because the "don't go crazy" dictum + eliminates most of the uses you'd have to be consistent with. + + 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="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>. + </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 the quantity you are representing is really a bit pattern + rather than a number, or unless you need defined + twos-complement overflow. In particular, do not use unsigned + types to say a number will never be negative. Instead, use + + assertions for this. + </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 NULL"> + <SUMMARY> + Use <code>0</code> for integers, <code>0.0</code> for reals, + <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>. Bjarne Stroustrup prefers an unadorned + <code>0</code>. We prefer <code>NULL</code> because it looks like a + pointer. In fact, some C++ compilers, such as gcc 4.1.0, 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> + Use <code>sizeof(<var>varname</var>)</code> instead of + <code>sizeof(<var>type</var>)</code> whenever possible. + </SUMMARY> + <BODY> + <p> + Use <code>sizeof(<var>varname</var>)</code> because it will update + appropriately if the type of the variable changes. + <code>sizeof(<var>type</var>)</code> may make sense in some cases, + but should generally be avoided because it can fall out of sync if + the variable's type changes. + </p> + <p> + <CODE_SNIPPET> + Struct data; + memset(&data, 0, sizeof(data)); + </CODE_SNIPPET> + <BAD_CODE_SNIPPET> + memset(&data, 0, sizeof(Struct)); + </BAD_CODE_SNIPPET> + </p> + </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> + </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++0x"> + <SUMMARY> + Use only approved libraries and language extensions from C++0x. + Currently, none are approved. + </SUMMARY> + <BODY> + <DEFINITION> + C++0x is the next ISO C++ standard, currently in + <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3092.pdf">final + committee draft</a> form. It contains + <a href="http://en.wikipedia.org/wiki/C%2B%2B0x">significant + changes</a> both to the language and libraries. + </DEFINITION> + <PROS> + We expect that C++0x will become the next 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 safety improvements. + </PROS> + <CONS> + <p> + The C++0x standard is substantialy more complex than its predecessor + (1,300 pages versus 800 pages), and is + unfamilar 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++0x 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++0x libraries and language features that have been approved + for use. Currently, no such features are approved. + Features will be approved individually as appropriate. + </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 a copyright notice, followed by a + description of the contents of the file. + </SUMMARY> + <BODY> + <SUBSECTION title="Legal Notice and Author Line"> + + + <p> + Every file should contain the following items, in order: + <ul> + <li>a copyright statement (for example, + <code>Copyright 2008 Google Inc.</code>)</li> + <li>a license boilerplate. Choose the appropriate boilerplate + for the license used by the project (for example, + Apache 2.0, BSD, LGPL, GPL)</li> + <li>an author line to identify the original author of the + file</li> + </ul> + </p> + <p> + If you make significant changes to a file that someone else + originally wrote, add yourself to the author line. This can + be very helpful when another + + contributor + has questions about the file and needs to know whom to contact + about it. + </p> + </SUBSECTION> + + <SUBSECTION title="File Contents"> + <p> + Every file should have a comment at the top, below the copyright + notice and author line, that describes the contents of the file. + </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 <code>NULL</code>. + </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 <code>NULL</code> 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="NULL, true/false, 1, 2, 3..."> + <p> + When you pass in <code>NULL</code>, 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 usually be written as complete + sentences with proper capitalization and periods at the end. + 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. Complete sentences are more + readable, and they provide some assurance that the comment is + complete and not an unfinished thought. + </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 your function is <code>const</code>, the <code>const</code> + keyword should be on the same line as the last parameter: + </p> + <CODE_SNIPPET> + // Everything in this function signature fits on a single line + ReturnType FunctionName(Type par) const { + ... + } + + // This function signature requires multiple lines, but + // the const keyword is on the line with the last parameter. + ReturnType ReallyLongFunctionName(Type par1, + Type par2) const { + ... + } + </CODE_SNIPPET> + <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> + If the function signature is so long that it cannot fit within + the maximum <a href="#Line_Length">line length</a>, you may + place all arguments on subsequent lines: + </p> + <CODE_SNIPPET> + if (...) { + ... + ... + if (...) { + DoSomethingThatRequiresALongFunctionName( + very_long_argument1, // 4 space indent + argument2, + argument3, + argument4); + } + </CODE_SNIPPET> + </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 { // The else goes on the same line as the closing brace. + ... + } + </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. 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. + 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; // C++ requires 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.188 +</p> + + + +<address> +Benjy Weinberger<br/> +Craig Silverstein<br/> +Gregory Eitzmann<br/> +Mark Mentovai<br/> +Tashana Landray +</address> + +</GUIDE> diff --git a/guides/styleguide.css b/guides/styleguide.css new file mode 100644 index 000000000..adba8f3cc --- /dev/null +++ b/guides/styleguide.css @@ -0,0 +1,147 @@ +body { + background-color: #fff; + color: #333; + font-family: sans-serif; + font-size: 10pt; + margin-right: 100px; + margin-left: 100px; +} + +h1, h2, h3, h4, h5, h6, .toc_title { + color: #06c; + margin-top: 2em; + margin-bottom: 1em; +} + +h1 { + text-align: center; + font-size: 18pt; +} + +h2, .toc_title { + font-weight: bold; + font-size: 12pt; + margin-left: -40px; +} + +h3, h4, h5, h6 { + font-size: 10pt; + margin-left: -20px; +} + +.toc_category, .toc_stylepoint { + font-size: 10pt; + padding-top: .3em; + padding-bottom: .3em; +} + +table { + border-collapse: collapse; +} + +td, th { + border: 1px solid #ccc; + padding: 2px 12px; + font-size: 10pt; +} + +.toc td, .toc th { + border-width: 1px 5px; +} + +code, samp, var { + color: #060; +} + +pre { + font-size: 10pt; + display: block; + color: #060; + background-color: #f8fff8; + border-color: #f0fff0; + border-style: solid; + border-top-width: 1px; + border-bottom-width: 1px; + border-right-width: 1px; + border-left-width: 5px; + padding-left: 12px; + padding-right: 12px; + padding-top: 4px; + padding-bottom: 4px; +} + +pre.badcode { + color: #c00; + background-color: #fff8f8; + border-color: #fff0f0; +} + +.showhide_button { + float: left; + cursor: pointer; + border-width: 1px; + border-style: solid; + border-color: #ddd #aaa #aaa #ddd; + padding: 0 3px 1px; + margin: 0 4px 8px 0; + border-radius: 3px; + -webkit-border-radius: 3px; + -moz-border-radius: 3px; +} + +.link_button { + float: left; + display: none; + background-color: #f8f8ff; + border-color: #f0f0ff; + border-style: solid; + border-width: 1px; + font-size: 75%; + margin-top: 0; + margin-left: -50px; + padding: 4px; + border-radius: 3px; + -webkit-border-radius: 3px; + -moz-border-radius: 3px; +} + +address { + text-align: right; +} + +hr { + margin-top: 3.5em; + border-width: 1px; + color: #fff; +} + +.stylepoint_section { + display: block; + margin-bottom: 1em; + color: #5588ff; + font-family: sans-serif; + font-size: 90%; + font-weight: bold; + margin-left: -2%; +} + +.stylepoint_subsection { + color: #667799; + font-family: sans-serif; + font-size: 90%; + font-weight: bold; + margin-left: -1%; +} + +.stylepoint_subsubsection { + color: #667799; + font-family: sans-serif; + font-size: 80%; + font-weight: bold; + margin-left: 0; +} + +.revision { + text-align: right; +} + diff --git a/guides/styleguide.xsl b/guides/styleguide.xsl new file mode 100644 index 000000000..38345d51d --- /dev/null +++ b/guides/styleguide.xsl @@ -0,0 +1,890 @@ +<xsl:stylesheet version="1.0" +xmlns:xsl="http://www.w3.org/1999/XSL/Transform" +xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" +xmlns:dc="http://purl.org/dc/elements/1.1/" +xmlns:dcq="http://purl.org/dc/qualifiers/1.0/" +xmlns:fo="http://www.w3.org/1999/XSL/Format" +xmlns:fn="http://www.w3.org/2005/xpath-functions"> + <xsl:output method="html"/> + <!-- Set to 1 to show explanations by default. Set to 0 to hide them --> + <xsl:variable name="show_explanation_default" select="0" /> + <!-- The characters within the Webdings font that show the triangles --> + <xsl:variable name="show_button_text" select="'▶'" /> + <xsl:variable name="hide_button_text" select="'▽'" /> + <!-- The suffix for names --> + <xsl:variable name="button_suffix" select="'__button'"/> + <xsl:variable name="body_suffix" select="'__body'"/> + <!-- For easy reference, the name of the button --> + <xsl:variable name="show_hide_all_button" select="'show_hide_all_button'"/> + + <!-- The top-level element --> + <xsl:template match="GUIDE"> + <HTML> + <HEAD> + <TITLE><xsl:value-of select="@title"/></TITLE> + <META http-equiv="Content-Type" content="text/html; charset=utf-8"/> + <LINK HREF="http://www.google.com/favicon.ico" type="image/x-icon" + rel="shortcut icon"/> + <LINK HREF="styleguide.css" + type="text/css" rel="stylesheet"/> + + <SCRIPT language="javascript" type="text/javascript"> + + function ShowHideByName(bodyName, buttonName) { + var bodyElements; + var linkElement; + if (document.getElementsByName) { + bodyElements = document.getElementsByName(bodyName); + linkElement = document.getElementsByName('link-' + buttonName)[0]; + } else { + bodyElements = [document.getElementById(bodyName)]; + linkElement = document.getElementById('link-' + buttonName); + } + if (bodyElements.length != 1) { + alert("ShowHideByName() got the wrong number of bodyElements: " + bodyElements.length); + } else { + var bodyElement = bodyElements[0]; + var buttonElement; + if (document.getElementsByName) { + var buttonElements = document.getElementsByName(buttonName); + buttonElement = buttonElements[0]; + } else { + buttonElement = document.getElementById(buttonName); + } + if (bodyElement.style.display == "none" || bodyElement.style.display == "") { + bodyElement.style.display = "inline"; + linkElement.style.display = "block"; + buttonElement.innerHTML = '<xsl:value-of select="$hide_button_text"/>'; + } else { + bodyElement.style.display = "none"; + linkElement.style.display = "none"; + buttonElement.innerHTML = '<xsl:value-of select="$show_button_text"/>'; + } + } + } + + function ShowHideAll() { + var allButton; + if (document.getElementsByName) { + var allButtons = document.getElementsByName("show_hide_all_button"); + allButton = allButtons[0]; + } else { + allButton = document.getElementById("show_hide_all_button"); + } + if (allButton.innerHTML == '<xsl:value-of select="$hide_button_text"/>') { + allButton.innerHTML = '<xsl:value-of select="$show_button_text"/>'; + SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '<xsl:value-of select="$show_button_text"/>'); + } else { + allButton.innerHTML = '<xsl:value-of select="$hide_button_text"/>'; + SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '<xsl:value-of select="$hide_button_text"/>'); + } + } + + // Recursively sets state of all children + // of a particular node. + function SetHiddenState(root, newState, newButton) { + for (var i = 0; i != root.length; i++) { + SetHiddenState(root[i].childNodes, newState, newButton); + if (root[i].className == 'showhide_button') { + root[i].innerHTML = newButton; + } + if (root[i].className == 'stylepoint_body' || + root[i].className == 'link_button') { + root[i].style.display = newState; + } + } + } + + + window.onload = function() { + // if the URL contains "?showall=y", expand the details of all children + { + var showHideAllRegex = new RegExp("[\\?&](showall)=([^&#]*)"); + var showHideAllValue = showHideAllRegex.exec(window.location.href); + if (showHideAllValue != null) { + if (showHideAllValue[2] == "y") { + SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '<xsl:value-of select="$hide_button_text"/>'); + } else { + SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '<xsl:value-of select="$show_button_text"/>'); + } + } + var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)"); + var showOneValue = showOneRegex.exec(window.location.href); + if (showOneValue != null) { + var body_name = showOneValue[2] + '<xsl:value-of select="$body_suffix"/>'; + var button_name = showOneValue[2] + '<xsl:value-of select="$button_suffix"/>'; + ShowHideByName(body_name, button_name); + } + + } + } + </SCRIPT> + </HEAD> + <BODY> + <H1><xsl:value-of select="@title"/></H1> + <xsl:apply-templates/> + </BODY> + </HTML> + </xsl:template> + + <xsl:template match="OVERVIEW"> + <xsl:variable name="button_text"> + <xsl:choose> + <xsl:when test="$show_explanation_default"> + <xsl:value-of select="$hide_button_text"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$show_button_text"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <DIV style="margin-left: 50%; font-size: 75%;"> + <P> + Each style point has a summary for which additional information is available + by toggling the accompanying arrow button that looks this way: + <SPAN class="showhide_button" style="margin-left: 0; float: none"> + <xsl:value-of select="$show_button_text"/></SPAN>. + You may toggle all summaries with the big arrow button: + </P> + <DIV style=" font-size: larger; margin-left: +2em;"> + <SPAN class="showhide_button" style="font-size: 180%; float: none"> + <xsl:attribute name="onclick"><xsl:value-of select="'javascript:ShowHideAll()'"/></xsl:attribute> + <xsl:attribute name="name"><xsl:value-of select="$show_hide_all_button"/></xsl:attribute> + <xsl:attribute name="id"><xsl:value-of select="$show_hide_all_button"/></xsl:attribute> + <xsl:value-of select="$button_text"/> + </SPAN> + Toggle all summaries + </DIV> + </DIV> + <xsl:call-template name="TOC"> + <xsl:with-param name="root" select=".."/> + </xsl:call-template> + <xsl:apply-templates/> + </xsl:template> + + <xsl:template match="PARTING_WORDS"> + <H2>Parting Words</H2> + <xsl:apply-templates/> + </xsl:template> + + <xsl:template match="CATEGORY"> + <DIV> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <H2> + <xsl:variable name="category_name"> + <xsl:call-template name="anchorname"> + <xsl:with-param name="sectionname" select="@title"/> + </xsl:call-template> + </xsl:variable> + <xsl:attribute name="name"><xsl:value-of select="$category_name"/></xsl:attribute> + <xsl:attribute name="id"><xsl:value-of select="$category_name"/></xsl:attribute> + <xsl:value-of select="@title"/> + </H2> + <xsl:apply-templates/> + </DIV> + </xsl:template> + + <xsl:template match="STYLEPOINT"> + <DIV> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <xsl:variable name="stylepoint_name"> + <xsl:call-template name="anchorname"> + <xsl:with-param name="sectionname" select="@title"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="button_text"> + <xsl:choose> + <xsl:when test="$show_explanation_default"> + <xsl:value-of select="$hide_button_text"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$show_button_text"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <H3> + <A> + <xsl:attribute name="name"><xsl:value-of select="$stylepoint_name"/></xsl:attribute> + <xsl:attribute name="id"><xsl:value-of select="$stylepoint_name"/></xsl:attribute> + <xsl:value-of select="@title"/> + </A> + </H3> + <xsl:variable name="buttonName"> + <xsl:value-of select="$stylepoint_name"/><xsl:value-of select="$button_suffix"/> + </xsl:variable> + <xsl:variable name="onclick_definition"> + <xsl:text>javascript:ShowHideByName('</xsl:text> + <xsl:value-of select="$stylepoint_name"/><xsl:value-of select="$body_suffix"/> + <xsl:text>','</xsl:text> + <xsl:value-of select="$buttonName"/> + <xsl:text>')</xsl:text> + </xsl:variable> + <SPAN class="link_button" id="link-{$buttonName}" name="link-{$buttonName}"> + <A> + <xsl:attribute name="href">?showone=<xsl:value-of select="$stylepoint_name"/>#<xsl:value-of select="$stylepoint_name"/></xsl:attribute> + link + </A> + </SPAN> + <SPAN class="showhide_button"> + <xsl:attribute name="onclick"><xsl:value-of select="$onclick_definition"/></xsl:attribute> + <xsl:attribute name="name"><xsl:value-of select="$buttonName"/></xsl:attribute> + <xsl:attribute name="id"><xsl:value-of select="$buttonName"/></xsl:attribute> + <xsl:value-of select="$button_text"/> + </SPAN> + <xsl:apply-templates> + <xsl:with-param name="anchor_prefix" select="$stylepoint_name" /> + </xsl:apply-templates> + </DIV> + </xsl:template> + + <xsl:template match="SUMMARY"> + <xsl:param name="anchor_prefix" /> + <DIV style="display:inline;"> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <xsl:apply-templates/> + </DIV> + </xsl:template> + + <xsl:template match="BODY"> + <xsl:param name="anchor_prefix" /> + <DIV> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <DIV class="stylepoint_body"> + <xsl:attribute name="name"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute> + <xsl:attribute name="id"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute> + <xsl:attribute name="style"> + <xsl:choose> + <xsl:when test="$show_explanation_default">display: inline</xsl:when> + <xsl:otherwise>display: none</xsl:otherwise> + </xsl:choose> + </xsl:attribute> + <xsl:apply-templates/> + </DIV> + </DIV> + </xsl:template> + + <xsl:template match="DEFINITION"> + <P> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <SPAN class="stylepoint_section">Definition: </SPAN> + <xsl:apply-templates/> + </P> + </xsl:template> + + <xsl:template match="PROS"> + <P> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <SPAN class="stylepoint_section">Pros: </SPAN> + <xsl:apply-templates/> + </P> + </xsl:template> + + <xsl:template match="CONS"> + <P> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <SPAN class="stylepoint_section">Cons: </SPAN> + <xsl:apply-templates/> + </P> + </xsl:template> + + <xsl:template match="DECISION"> + <P> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <SPAN class="stylepoint_section">Decision: </SPAN> + <xsl:apply-templates/> + </P> + </xsl:template> + + <xsl:template match="TODO"> + <P> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <DIV style="font-size: 150%;">TODO: + <xsl:apply-templates/> + </DIV> + </P> + </xsl:template> + + <xsl:template match="SUBSECTION"> + <P> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <SPAN class="stylepoint_subsection"><xsl:value-of select="@title"/> </SPAN> + <xsl:apply-templates/> + </P> + </xsl:template> + + <xsl:template match="SUBSUBSECTION"> + <P> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <SPAN class="stylepoint_subsubsection"><xsl:value-of select="@title"/> </SPAN> + <xsl:apply-templates/> + </P> + </xsl:template> + + <xsl:template match="CODE_SNIPPET"> + <DIV> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <PRE><xsl:call-template name="print_without_leading_chars"> + <xsl:with-param name="text" select="."/> + <xsl:with-param name="strip" select="1"/> + <xsl:with-param name="is_firstline" select="1"/> + <xsl:with-param name="trim_count"> + <xsl:call-template name="num_leading_spaces"> + <xsl:with-param name="text" select="."/> + <xsl:with-param name="max_so_far" select="1000"/> + </xsl:call-template> + </xsl:with-param> + </xsl:call-template></PRE> + </DIV> + </xsl:template> + + <xsl:template match="BAD_CODE_SNIPPET"> + <DIV> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <PRE class="badcode"><xsl:call-template name="print_without_leading_chars"> + <xsl:with-param name="text" select="."/> + <xsl:with-param name="strip" select="1"/> + <xsl:with-param name="is_firstline" select="1"/> + <xsl:with-param name="trim_count"> + <xsl:call-template name="num_leading_spaces"> + <xsl:with-param name="text" select="."/> + <xsl:with-param name="max_so_far" select="1000"/> + </xsl:call-template> + </xsl:with-param> + </xsl:call-template></PRE> + </DIV> + </xsl:template> + + <xsl:template match="PY_CODE_SNIPPET"> + <DIV> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <PRE><xsl:call-template name="print_python_code"> + <xsl:with-param name="text" select="."/> + </xsl:call-template></PRE> + </DIV> + </xsl:template> + + <xsl:template match="BAD_PY_CODE_SNIPPET"> + <DIV> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <PRE class="badcode"><xsl:call-template name="print_python_code"> + <xsl:with-param name="text" select="."/> + </xsl:call-template></PRE> + </DIV> + </xsl:template> + + <xsl:template match="FUNCTION"> + <xsl:call-template name="print_function_name"> + <xsl:with-param name="text" select="."/> + </xsl:call-template> + </xsl:template> + + <xsl:template match="SYNTAX"> + <I> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <xsl:apply-templates/> + </I> + </xsl:template> + + + <!-- This passes through any HTML elements that the + XML doc uses for minor formatting --> + <xsl:template match="a|address|blockquote|br|center|cite|code|dd|div|dl|dt|em|hr|i|img|li|ol|p|pre|span|table|td|th|tr|ul|var|A|ADDRESS|BLOCKQUOTE|BR|CENTER|CITE|CODE|DD|DIV|DL|DT|EM|HR|I|LI|OL|P|PRE|SPAN|TABLE|TD|TH|TR|UL|VAR"> + <xsl:element name="{local-name()}"> + <xsl:copy-of select="@*"/> + <xsl:apply-templates/> + </xsl:element> + </xsl:template> + + <!-- Builds the table of contents --> + <xsl:template name="TOC"> + <xsl:param name="root"/> + <DIV class="toc"> + <DIV class="toc_title">Table of Contents</DIV> + <TABLE> + <xsl:for-each select="$root/CATEGORY"> + <TR valign="top"> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <TD> + <DIV class="toc_category"> + <A> + <xsl:attribute name="href"> + <xsl:text>#</xsl:text> + <xsl:call-template name="anchorname"> + <xsl:with-param name="sectionname" select="@title"/> + </xsl:call-template> + </xsl:attribute> + <xsl:value-of select="@title"/> + </A> + </DIV> + </TD><TD> + <DIV class="toc_stylepoint"> + <xsl:for-each select="./STYLEPOINT"> + <SPAN style="padding-right: 1em; white-space:nowrap;"> + <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> + <A> + <xsl:attribute name="href"> + <xsl:text>#</xsl:text> + <xsl:call-template name="anchorname"> + <xsl:with-param name="sectionname" select="@title"/> + </xsl:call-template> + </xsl:attribute> + <xsl:value-of select="@title"/> + </A> + </SPAN> + <xsl:text> </xsl:text> + </xsl:for-each> + </DIV> + </TD> + </TR> + </xsl:for-each> + </TABLE> + </DIV> + </xsl:template> + + <xsl:template name="TOC_one_stylepoint"> + <xsl:param name="stylepoint"/> + </xsl:template> + + <!-- Creates a standard anchor given any text. + Substitutes underscore for characters unsuitable for URLs --> + <xsl:template name="anchorname"> + <xsl:param name="sectionname"/> + <!-- strange quoting necessary to strip apostrophes --> + <xsl:variable name="bad_characters" select="" ()#'""/> + <xsl:value-of select="translate($sectionname,$bad_characters,'_____')"/> + </xsl:template> + + <!-- Given text, evaluates to the number of leading spaces. --> + <!-- TODO(csilvers): deal well with leading tabs (treat as 8 spaces?) --> + <xsl:template name="num_leading_spaces_one_line"> + <xsl:param name="text"/> + <xsl:param name="current_count"/> + <xsl:choose> + <xsl:when test="starts-with($text, ' ')"> + <xsl:call-template name="num_leading_spaces_one_line"> + <xsl:with-param name="text" select="substring($text, 2)"/> + <xsl:with-param name="current_count" select="$current_count + 1"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$current_count"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Given a block of text, each line terminated by \n, evaluates to + the indentation-level of that text; that is, the largest number + n such that every non-blank line starts with at least n spaces. --> + <xsl:template name="num_leading_spaces"> + <xsl:param name="text"/> + <xsl:param name="max_so_far"/> + <!-- TODO(csilvers): deal with case text doesn't end in a newline --> + <xsl:variable name="line" select="substring-before($text, '
')"/> + <xsl:variable name="rest" select="substring-after($text, '
')"/> + <xsl:variable name="num_spaces_this_line"> + <xsl:choose> + <xsl:when test="$line=''"> + <xsl:value-of select="$max_so_far"/> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="num_leading_spaces_one_line"> + <xsl:with-param name="text" select="$line"/> + <xsl:with-param name="current_count" select="0"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:variable name="new_max_so_far"> + <xsl:choose> + <xsl:when test="$num_spaces_this_line < $max_so_far"> + <xsl:value-of select="$num_spaces_this_line"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$max_so_far"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <!-- now check if we're on the last line, and if not, recurse --> + <xsl:if test="$rest=''"> + <xsl:value-of select="$new_max_so_far"/> + </xsl:if> + <xsl:if test="not($rest='')"> + <xsl:call-template name="num_leading_spaces"> + <xsl:with-param name="text" select="$rest"/> + <xsl:with-param name="max_so_far" select="$new_max_so_far"/> + </xsl:call-template> + </xsl:if> + </xsl:template> + + <!-- Given text, determine the starting position of code. + This similar to num_leading_spaces_one_line but treats "Yes:" and "No:" + as spaces. Also, if there is no code on the first line, it searches + subsequent lines until a non-empty line is found. + Used to find the start of code in snippets like: + Yes: if(foo): + No : if(foo): + As well as: + Yes: + if (foo): + --> + <xsl:template name="code_start_index"> + <xsl:param name="text"/> + <xsl:param name="current_count"/> + <xsl:choose> + <xsl:when test="starts-with($text, ' ')"> + <xsl:call-template name="code_start_index"> + <xsl:with-param name="text" select="substring($text, 2)"/> + <xsl:with-param name="current_count" select="$current_count + 1"/> + </xsl:call-template> + </xsl:when> + <xsl:when test="starts-with($text, 'Yes:')"> + <xsl:call-template name="code_start_index"> + <xsl:with-param name="text" select="substring($text, 5)"/> + <xsl:with-param name="current_count" select="$current_count + 4"/> + </xsl:call-template> + </xsl:when> + <xsl:when test="starts-with($text, 'No:')"> + <xsl:call-template name="code_start_index"> + <xsl:with-param name="text" select="substring($text, 4)"/> + <xsl:with-param name="current_count" select="$current_count + 3"/> + </xsl:call-template> + </xsl:when> + <!-- This is only reached if the first line is entirely whitespace or + contains nothing but "Yes:" or "No:"--> + <xsl:when test="starts-with($text, '
')"> + <xsl:call-template name="code_start_index"> + <xsl:with-param name="text" select="substring($text, 2)"/> + <xsl:with-param name="current_count" select="0"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$current_count"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Helper for ends_with_colon. Determine whether the given line is nothing + but spaces and python-style comments. --> + <xsl:template name="is_blank_or_comment"> + <xsl:param name="line"/> + <xsl:choose> + <xsl:when test="$line = ''"> + <xsl:value-of select="1"/> + </xsl:when> + <xsl:when test="starts-with($line, '
')"> + <xsl:value-of select="1"/> + </xsl:when> + <xsl:when test="starts-with($line, '#')"> + <xsl:value-of select="1"/> + </xsl:when> + <xsl:when test="starts-with($line, ' ')"> + <xsl:call-template name="is_blank_or_comment"> + <xsl:with-param name="line" select="substring($line, 2)"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="0"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Determine whether the given line ends with a colon. Note that Python + style comments are ignored so the following lines return True: + - def foo(): + - def foo(): # Bar + - if(foo): + + But some code may confuse this function. For example the following are + also consider to "end_with_colon" even though they don't for Python + - foo(": #") + - foo() # No need for : + --> + <xsl:template name="ends_with_colon"> + <xsl:param name="line"/> + <xsl:param name="found_colon"/> + <xsl:choose> + <xsl:when test="$line = ''"> + <xsl:value-of select="$found_colon"/> + </xsl:when> + <xsl:when test="starts-with($line, '
')"> + <xsl:value-of select="$found_colon"/> + </xsl:when> + <xsl:when test="starts-with($line, ' ')"> + <xsl:call-template name="ends_with_colon"> + <xsl:with-param name="line" select="substring($line, 2)"/> + <xsl:with-param name="found_colon" select="$found_colon"/> + </xsl:call-template> + </xsl:when> + <xsl:when test="starts-with($line, ':')"> + <xsl:variable name="rest_is_comment"> + <xsl:call-template name="is_blank_or_comment"> + <xsl:with-param name="line" select="substring($line, 2)"/> + </xsl:call-template> + </xsl:variable> + <xsl:choose> + <xsl:when test="$rest_is_comment = '1'"> + <xsl:value-of select="1"/> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="ends_with_colon"> + <xsl:with-param name="line" select="substring($line, 2)"/> + <xsl:with-param name="found_colon" select="0"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="ends_with_colon"> + <xsl:with-param name="line" select="substring($line, 2)"/> + <xsl:with-param name="found_colon" select="0"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Prints one line of python code with proper indent and calls itself + recursively for the rest of the text. + This template uses "a", "b", "c" and "d" to refer to four key column + numbers. They are: + - a: the indentation common to all lines in a code snippet. This is + stripped out to allow for cleaner code in the xml. + - b: the indentation of the most out-dented line of code. This is + different from "a" when code is labelled with "Yes:" or "No:" + - c: the indentation of the current python block, in other words, the + indentation of the first line of this block, which is the + indentation of the last line we saw that ended with a colon. + - d: the "total" indentation of the line, ignorng possible "Yes:" or + "No:" text on the line. + + For example, for the last line of the following code snippet, the + positions of a, b, c and d are indicated below: + Yes: def Foo(): + if bar(): + a += 1 + baz() + a b c d + + The algorithm is: + 1) Split the text into first line and the rest. Note that the + substring-before function is supposed to handle the case where the + character is not present in the string but does not so we + automatically ignore the last line of the snippet which is always + empty (the closing snippet tag). This is consistent with the + behavior or print_without_leading_chars. + 2) If the current is empty (only whitespace), print newline and call + itself recursively on the rest of the text with the rest of the + parameters unchanged. + 3) Otherwise, measure "d" + 4) Measure "c" by taking: + - the value of "d" if the previous line ended with a colon or the + current line is outdented compare to the previous line + - the indent of the previous line otherwise + 5) Print line[a:c] (Note that we ignore line[0:a]) + 6) Print line[b:c] in an external span (in order to double the block + indent in external code). + 7) Print line[c:<end>] with function names processed to produce both + internal and external names. + 8) If there are more lines, recurse. + --> + <xsl:template name="print_python_line_recursively"> + <xsl:param name="text"/> + <xsl:param name="a"/> + <xsl:param name="b"/> + <xsl:param name="previous_indent"/> + <xsl:param name="previous_ends_with_colon"/> + <xsl:param name="is_first_line"/> + <xsl:variable name="line" select="substring-before($text, '
')"/> + <xsl:variable name="rest" select="substring-after($text, '
')"/> + <xsl:choose> + <xsl:when test="substring($line, $b) = '' and not($rest = '')"> + <xsl:if test="not($is_first_line = '1')"> + <xsl:text>
</xsl:text> + </xsl:if> + <xsl:call-template name="print_python_line_recursively"> + <xsl:with-param name="text" select="$rest"/> + <xsl:with-param name="a" select="$a"/> + <xsl:with-param name="b" select="$b"/> + <xsl:with-param name="previous_indent" select="$previous_indent"/> + <xsl:with-param name="previous_ends_with_colon" + select="$previous_ends_with_colon"/> + <xsl:with-param name="is_first_line" select="0"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:variable name="indent_after_b"> + <xsl:call-template name="num_leading_spaces_one_line"> + <xsl:with-param name="text" select="substring($line, $b + 1)"/> + <xsl:with-param name="current_count" select="0"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="d" select="$b + $indent_after_b"/> + <xsl:variable name="c"> + <xsl:choose> + <xsl:when test="$previous_ends_with_colon = '1' or + $previous_indent > $d"> + <xsl:value-of select="$d"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$previous_indent"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:value-of select="substring($line, $a + 1, $c - $a)"/> + <span class="external"> + <xsl:value-of select="substring($line, $b + 1, $c - $b)"/> + </span> + <xsl:call-template name="munge_function_names_in_text"> + <xsl:with-param name="stripped_line" + select="substring($line, $c + 1)"/> + </xsl:call-template> + <xsl:if test="not(substring($rest, $a) = '')"> + <xsl:text>
</xsl:text> + <xsl:call-template name="print_python_line_recursively"> + <xsl:with-param name="text" select="$rest"/> + <xsl:with-param name="a" select="$a"/> + <xsl:with-param name="b" select="$b"/> + <xsl:with-param name="previous_indent" select="$c"/> + <xsl:with-param name="previous_ends_with_colon"> + <xsl:call-template name="ends_with_colon"> + <xsl:with-param name="line" select="$line"/> + <xsl:with-param name="found_colon" select="0"/> + </xsl:call-template> + </xsl:with-param> + <xsl:with-param name="is_first_line" select="0"/> + </xsl:call-template> + </xsl:if> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Print python code with internal and external styles. + In order to conform with PEP-8 externally, we identify 2-space indents + and an external-only 4-space indent. + Function names that are marked with $$FunctionName/$$ have an external + lower_with_underscore version added. --> + <xsl:template name="print_python_code"> + <xsl:param name="text"/> + + <xsl:variable name="a"> + <xsl:call-template name="num_leading_spaces"> + <xsl:with-param name="text" select="."/> + <xsl:with-param name="max_so_far" select="1000"/> + </xsl:call-template> + </xsl:variable> + + <xsl:variable name="b"> + <xsl:call-template name="code_start_index"> + <xsl:with-param name="text" select="$text"/> + <xsl:with-param name="current_count" select="0"/> + </xsl:call-template> + </xsl:variable> + + <xsl:call-template name="print_python_line_recursively"> + <xsl:with-param name="text" select="$text"/> + <xsl:with-param name="a" select="$a"/> + <xsl:with-param name="b" select="$b"/> + <xsl:with-param name="previous_indent" select="$b"/> + <xsl:with-param name="previous_ends_with_colon" select="0"/> + <xsl:with-param name="is_first_line" select="1"/> + </xsl:call-template> + </xsl:template> + + <!-- Given a block of text, each line terminated by \n, and a number n, + emits the text with the first n characters of each line + deleted. If strip==1, then we omit blank lines at the beginning + and end of the text (but not the middle!) --> + <!-- TODO(csilvers): deal well with leading tabs (treat as 8 spaces?) --> + <xsl:template name="print_without_leading_chars"> + <xsl:param name="text"/> + <xsl:param name="trim_count"/> + <xsl:param name="strip"/> + <xsl:param name="is_firstline"/> + <!-- TODO(csilvers): deal with case text doesn't end in a newline --> + <xsl:variable name="line" select="substring-before($text, '
')"/> + <xsl:variable name="rest" select="substring-after($text, '
')"/> + <xsl:variable name="stripped_line" select="substring($line, $trim_count+1)"/> + <xsl:choose> + <!-- $line (or $rest) is considered empty if we'd trim the entire line --> + <xsl:when test="($strip = '1') and ($is_firstline = '1') and + (string-length($line) <= $trim_count)"> + </xsl:when> + <xsl:when test="($strip = '1') and + (string-length($rest) <= $trim_count)"> + <xsl:value-of select="$stripped_line"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$stripped_line"/> + <xsl:text>
</xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:if test="not($rest='')"> + <xsl:call-template name="print_without_leading_chars"> + <xsl:with-param name="text" select="$rest"/> + <xsl:with-param name="trim_count" select="$trim_count"/> + <xsl:with-param name="strip" select="$strip"/> + <xsl:with-param name="is_firstline" select="0"/> + </xsl:call-template> + </xsl:if> + </xsl:template> + + <!-- Given a line of code, find function names that are marked with $$ /$$ and + print out the line with the internal and external versions of the + function names.--> + <xsl:template name="munge_function_names_in_text"> + <xsl:param name="stripped_line"/> + <xsl:choose> + <xsl:when test="contains($stripped_line, '$$')"> + <xsl:value-of select="substring-before($stripped_line, '$$')"/> + <xsl:call-template name="print_function_name"> + <xsl:with-param name="text" select="substring-after(substring-before($stripped_line, '/$$'), '$$')"/> + </xsl:call-template> + <xsl:call-template name="munge_function_names_in_text"> + <xsl:with-param name="stripped_line" select="substring-after($stripped_line, '/$$')"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$stripped_line"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Given a function name, print out both the internal and external version + of the function name in their respective spans.--> + <xsl:template name="print_function_name"> + <xsl:param name="text"/> + <xsl:call-template name="convert_camel_case_to_lowercase_with_under"> + <xsl:with-param name="text" select="$text"/> + </xsl:call-template> + </xsl:template> + + <!-- Given a single word of text convert it from CamelCase to + lower_with_under. + This means replacing each uppercase character with _ followed by the + lowercase version except for the first character which is replaced + without adding the _.--> + <xsl:template name="convert_camel_case_to_lowercase_with_under"> + <xsl:param name="text"/> + <xsl:param name="is_recursive_call"/> + <xsl:variable name="first_char" select="substring($text, 1, 1)"/> + <xsl:variable name="rest" select="substring($text, 2)"/> + <xsl:choose> + <xsl:when test="contains('ABCDEFGHIJKLMNOPQRSTUVWXYZ', $first_char)"> + <xsl:if test="$is_recursive_call='1'"> + <xsl:text>_</xsl:text> + </xsl:if> + <xsl:value-of select="translate($first_char, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$first_char" /> + </xsl:otherwise> + </xsl:choose> + <xsl:if test="not($rest='')"> + <xsl:call-template name="convert_camel_case_to_lowercase_with_under"> + <xsl:with-param name="text" select="$rest"/> + <xsl:with-param name="is_recursive_call" select="1"/> + </xsl:call-template> + </xsl:if> + </xsl:template> +</xsl:stylesheet> + |