cppguide.xml

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
<GUIDE title="OpenGeoSys C++ Style Guide">

<p>
This styleguide is derived from the <a href="http://code.google.com/p/google-styleguide/">Google C++ Style Guide</a> and is hosted on <a href="https://github.com/ufz/styleguide">Github</a>. Some <a href="https://github.com/ufz/styleguide/compare/9df0dce4fa1441f9de7ff99760c61e01b6d3b79c...gh-pages">modifications</a> were made to match the <a href="http://www.opengeosys.net" target="blank">OpenGeoSys</a> development needs. The original authors are Benjy Weinberger, Craig Silverstein, Gregory Eitzmann,	Mark Mentovai and Tashana Landray.
</p>

<CATEGORY title="Most important rules to remember">

  <ul>
  <li><strong>Never</strong> use global variables. <a href="#Global_variables">More&#8230;</a></li>
  <li>Give <strong>descriptive names</strong> to functions, variables, and file names; eschew abbreviation. <a href="#Naming">More&#8230;</a>

  <ul>
  <li>Variable names start lowercase and then camel case. Class member
  variables start with an underscore.</li>
  <li>Regular functions or class methods start lowercase an then camel case.</li>
  </ul></li>
  <li>Define only <strong>one class per header file</strong>. The file name must match the
  class that is defined in the file. <a href="#Header_Files">More&#8230;</a></li>
  <li><strong>Document</strong> your code. <a href="#Comments">More&#8230;</a></li>
  </ul>

</CATEGORY>

<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="Automatic code styling">
  <p>
  This guide comes with a <a HREF="http://ufz.github.com/styleguide/uncrustify.cfg">
  configuration file</a> for the <a HREF="http://uncrustify.sourceforge.net/">
  uncrustify</a> automatic code styler. With this tool you can restyle your source
  code according to this styleguide. The config file is not finished yet. For
  creating the config file the <a HREF="http://universalindent.sourceforge.net/">
  UniversalIndentGUI</a> was used. See
  <a HREF="https://github.com/ufz/styleguide/blob/gh-pages/README.md">this link</a>
  for instructions how to apply the formatting to your code.
  </p>
</CATEGORY>

</OVERVIEW>

<CATEGORY title="Header Files">
  <p>
    In general, every <code>.cpp</code> file should have an associated
    <code>.h</code> file. There are some common exceptions, such as
    unittests and small <code>.cpp</code> files containing just a
    <code>main()</code> function. There is only one class per header file.
  </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>&lt;FILENAME_WITHOUT_ENDING&gt;</i>_H</code>.
    </SUMMARY>
    <BODY>

      <p>
        Every file in a project should be named unique so it is
        sufficient to only use the filename. For example, the file
        <code>Foo.h</code> should
        have the following guard:
      </p>
      <CODE_SNIPPET>
         #ifndef FOO_H
         #define FOO_H

         ...

         #endif  // FOO_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>MyClass</code> class in ways that do not require access to
        the declaration of the <code>MyClass</code> class, your header
        file can just forward declare <code>class MyClass;</code> instead
        of having to <code>#include "MyClass.h"</code>. Note the special
        notation of classes inside namespaces.
      </p>
      <CODE_SNIPPET>
        class MyClass;                      // Forward declaration
        namespace MyNamespace { class A; }  // Forward declaration of MyNamespace::A
      </CODE_SNIPPET>
      <p>instead of</p>
      <BAD_CODE_SNIPPET>
        include "MyClass.h" // Bad include
        include "A.h"       // Bad include
      </BAD_CODE_SNIPPET>
      <p>
        Never forward declare somethin the <code>std</code> namespace.
      </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&amp;</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&amp;</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>
        Of course, <code>.cpp</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.
      </SUBSECTION>
    </BODY>
  </STYLEPOINT>

  <STYLEPOINT title="Inline Functions">
    <SUMMARY>
      Define functions inline only when they are small, say, 1-2 lines.
      Trust the compiler in doing optimizations.
    </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. Also modern compiler do a very good
        job on optimizing code.
      </CONS>
      <DECISION>
        <p>
          Because of compiler doing optimizations you do not have to
          care that much about inlining. The compiler often does this
          for you when useful. Otherwise a decent rule of thumb is to
          not inline a function if it is
          more than 2 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="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: (class own header file), 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 only the filename itself.

        <code>Logging.h</code>
        should be included as
      </p>
      <CODE_SNIPPET>
        #include "Logging.h"
      </CODE_SNIPPET>
      <p>
        In <code><var>Foo</var>.cpp</code> order your includes as
        follows:
      </p>
      <ol>
        <li> <code><var>Foo</var>.h</code></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>.cpp</code>.
      </p>

      <p>
        Within each section it is nice to order the includes
        alphabetically.
      </p>
      <p>
        For example, the includes in

        <code>Fooserver.cpp</code>
        might look like this:
      </p>
      <CODE_SNIPPET>
        #include "Fooserver.h"

        #include &lt;sys/types.h&gt;
        #include &lt;unistd.h&gt;

        #include &lt;hash_map&gt;
        #include &lt;vector&gt;

        #include "Basictypes.h"
        #include "CommandlineFlags.h"
        #include "Bar.h"
      </CODE_SNIPPET>
    </BODY>
  </STYLEPOINT>
</CATEGORY>

<CATEGORY title="Scoping">
  <STYLEPOINT title="Namespaces">
    <SUMMARY>
      Choose the name of the namespace based on the project component
      it belongs to.
      Do not use a <SYNTAX>using-directive</SYNTAX> in header files.
    </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>
      </PROS>
      <DECISION>
        <p>
          Use namespaces according to the policy described below.
        </p>

        <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 .cpp file
                   namespace MyNamespace
                   {

                   // Definition of functions is within scope of the namespace.
                   void MyClass::foo()
                   {
                       ...
                   }

                   }  // namespace MyNamespace
                 </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 use a <SYNTAX>using-declaration</SYNTAX>
                 anywhere in a <code>.cpp</code> file, and in functions,
                 methods or classes in <code>.h</code> files.
                 <CODE_SNIPPET>
                   // OK in .cpp files.
                   using Foo;
                 </CODE_SNIPPET>
                 </li>
          </ul>
        </SUBSECTION>
      </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; never use completely global functions.
    </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>
      </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
        &lt; 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 &lt; 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 &lt; 1000000; ++i)
            f.doSomething(i);
      </CODE_SNIPPET>
    </BODY>
  </STYLEPOINT>

  <STYLEPOINT title="Global variables">
    <SUMMARY>
      NEVER use global variables! Period.
    </SUMMARY>
    <BODY>
    </BODY>
  </STYLEPOINT>

  <STYLEPOINT title="Static Variables">
    <SUMMARY>
      Static 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
        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 variable of a class type, consider
        initializing a pointer (which will never be freed), from either your
        main() function or from pthread_once().
      </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>
        <p>
          Finally, constructors that take only an initializer_list may be
          non-explicit. This is to permit construction of your type using the
          assigment form for brace init lists (i.e. <code>MyType m = {1, 2}
          </code>).
        </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&amp;);               \
            void operator=(const TypeName&amp;)
        </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>.
        </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.
    </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 most of the superclasses
        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="Abstract classes">
    <SUMMARY>
      Classes that have at least one pure virtual method should be prefixed by
      <code>Abstract</code>.
    </SUMMARY>
    <BODY>
      <DEFINITION>
        <p>
        A class that has at least one pure virtual method ("<code>= 0</code>")
        is abstract, that is it cannot instantiated directly. It is used as a
        base class for another class implementing that pure virtual method.
        </p>
        <p>
        When all methods of a class are pure virtual it is considered a
        <a HREF="#Interfaces">interface</a>.
        </p>
      </DEFINITION>
    </BODY>
  </STYLEPOINT>

  <STYLEPOINT title="Interfaces">
    <SUMMARY>
      Classes that satisfy certain conditions are allowed, but not required, to
      start with an <code>I</code> prefix.
    </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>I</code> prefix 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 interface
        property may be considered an implementation detail that shouldn't
        be exposed to clients.
      </CONS>
      <DECISION>
        A class may start with <code>I</code> only if it meets the
        above requirements.  We do not require the converse.
      </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>&amp;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&amp;</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&amp;</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&lt;&lt;(ostream&amp;, const
          T&amp;)</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&lt;</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.
      Typically a variable would be
      called <code>_foo</code> and the accessor function
      <code>getFoo()</code>.  You may also want a mutator function
      <code>setFoo()</code>.
    </SUMMARY>
    <BODY>
      <p>
        Exception: <code>static const</code> data members need not be <code>private</code>.
      </p>
      <p>
        The definitions of accessors are usually inlined in the header
        file.
      </p>
      <BAD_CODE_SNIPPET>
        class Bar
        {
        public:
            int foo;
        }
      </BAD_CODE_SNIPPET>
      <CODE_SNIPPET>
        class Bar
        {
        public:
            int getFoo() const { return _foo; }
            void setFoo(const int value) { _foo = value; }

        private:
            int _foo;
        }
      </CODE_SNIPPET>
      <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>.cpp</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&lt;const
          T&gt;</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="Friends">
    <SUMMARY>
      We allow use of <code>friend</code> classes and functions,
      within reason.
    </SUMMARY>
    <BODY>
      <p>
        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>
    </BODY>
  </STYLEPOINT>

  <STYLEPOINT title="Casting">
    <SUMMARY>
      Use C++ casts like <code>static_cast&lt;&gt;()</code>.  Do not use
      other cast formats like <code>int y = (int)x;</code> or
      <code>int y = int(x);</code>.
    </SUMMARY>
    <BODY>
      <DEFINITION>
        C++ introduced a different cast system from C that
        distinguishes the types of cast operations.
      </DEFINITION>
      <PROS>
        The problem with C casts is the ambiguity of the operation;
        sometimes you are doing a <em>conversion</em> (e.g.,
        <code>(int)3.5</code>) and sometimes you are doing a
        <em>cast</em> (e.g., <code>(int)"hello"</code>); C++ casts
        avoid this.  Additionally C++ casts are more visible when
        searching for them.
      </PROS>
      <CONS>
        The syntax is nasty.
      </CONS>
      <DECISION>
        <p>
          Do not use C-style casts.  Instead, use these C++-style
          casts.

        </p>
        <ul>

          <li> Use <code>static_cast</code> as the equivalent of a
               C-style cast that does value conversion, or when you need to explicitly up-cast
               a pointer from a class to its superclass.
               </li>
          <li> Use <code>const_cast</code> to remove the <code>const</code>
               qualifier (see <a HREF="#Use_of_const">const</a>).
               </li>


          <li> Use <code>reinterpret_cast</code> to do unsafe
               conversions of pointer types to and from integer and
               other pointer types. Use this only if you know what you are
               doing and you understand the aliasing issues.

               </li>
        </ul>
      </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>
    </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="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, NULL and nullptr">
  <SUMMARY>
    Use <code>0</code> for integers, <code>0.0</code> for reals,
    <code>nullptr</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>, 
      <code>NULL</code> and <code>nullptr</code>. We use <code>nullptr</code> 
      because it specifies exactly what is meant.
    </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(&amp;data, 0, sizeof(data));
      </CODE_SNIPPET>
      <BAD_CODE_SNIPPET>
        memset(&amp;data, 0, sizeof(Struct));
      </BAD_CODE_SNIPPET>
    </p>
  </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 imperative 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 numErrors;                  // Good.
          int numCompletedConnections;    // 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 nCompConns;                // Bad - ambiguous abbreviation.
        </BAD_CODE_SNIPPET>
        <p>
          Type and variable names should typically be nouns: e.g.,
          <code>fileOpener</code>, <code>numErrors</code>.
        </p>
        <p>
          Function names should typically be imperative (that is they
          should be commands): e.g., <code>openFile()</code>,
          <code>setNumErrors()</code>.
        </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 numDnsConnections;  // Most people know what "DNS" stands for.
          int priceCountReader;   // OK, price count. Makes sense.
        </CODE_SNIPPET>
        <BAD_CODE_SNIPPET>
          // Bad!
          // Abbreviations can be confusing or ambiguous outside a small group.
          int wgcConnections;  // Only your group knows what this stands for.
          int pcReader;        // Lots of things can be abbreviated "pc".
        </BAD_CODE_SNIPPET>
        <p>
          Never abbreviate by leaving out letters:
        </p>
        <CODE_SNIPPET>
          int errorCount;  // Good.
        </CODE_SNIPPET>
        <BAD_CODE_SNIPPET>
          int errorCnt;    // Bad.
        </BAD_CODE_SNIPPET>
      </SUBSECTION>
    </BODY>
  </STYLEPOINT>

  <STYLEPOINT title="File Names">
    <SUMMARY>
      Filenames should be camel case and do not include underscores
      (<code>_</code>) or dashes (<code>-</code>). The name must match the
      class that is defined in the file.
    </SUMMARY>
    <BODY>
      <p>
        Examples of acceptable file names for the class <code>MyUsefulClass</code>:
      </p>
      <p>
        <code>
          MyUsefulClass.h<br/>
          MyUsefulClass.cpp<br/>
        </code>
      </p>
      <p>
        C++ files should end in <code>.cpp</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>
        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.
      </p>
    </BODY>
  </STYLEPOINT>
  
  <STYLEPOINT title="Template File Names">
    <p>
      In addition to the general naming scheme the template implementation
      should be placed in a file named <code>MyTemplateClass-impl.h</code>.
      This file gets included at the end of the header file
      <code>MyTemplateClass.h</code>.
    </p>
  </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 &#8212; classes, structs, typedefs, and enums
        &#8212; have the same naming convention. Type names should start
        with a capital letter and have a capital letter for each new
        word. No underscores. This is the same convention as for
        <a HREF="#File Names">file namea</a>. For example:
      </p>
      <CODE_SNIPPET>
        // classes and structs
        class UrlTable { ...
        class UrlTableTester { ...
        struct UrlTableProperties { ...

        // typedefs
        typedef hash_map&lt;UrlTableProperties *, string&gt; PropertiesMap;

        // enums
        enum UrlTableErrors { ...
      </CODE_SNIPPET>
    </BODY>
  </STYLEPOINT>

  <STYLEPOINT title="Variable Names">
    <SUMMARY>
      Variable names start lowercase and then camel case. Class member
      variables start with an underscore.  For
      instance: <code>myExcitingLocalVariable</code>,
      <code>_myExcitingMemberVariable</code>. As an alternative you can use
      lowercase names with underscores: <code>_my_exciting_member_variable</code>.
      But be consistent in a file!
    </SUMMARY>
    <BODY>
      <SUBSECTION title="Struct Variables">
        <p>
          Data members in structs should be named like regular
          variables without the starting underscore that data members
          in classes have.
        </p>
        <CODE_SNIPPET>
          struct UrlTableProperties
          {
              string name;
              int numEntries;
          }
        </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>

    </BODY>
  </STYLEPOINT>


  <STYLEPOINT title="Function Names">
    <SUMMARY>
      Function names should represent an action. Regular functions start
      lowercase an then camel case. Accessors and mutators match
      the name of the variable with a "get" or "set" prefix: <code>doSomeStuff()</code>,
      <code>doSomeStuffOnThing()</code>,
      <code>getMyExcitingMemberVariable()</code>,
      <code>setMyExcitingMemberVariable()</code>.
    </SUMMARY>
    <BODY>
      <SUBSECTION title="Regular Functions">
        <p>
          Functions should start with a lowercase letter and have a
          capital letter for each new word. No underscores.
        </p>
        <CODE_SNIPPET>
          addTableEntry()
          deleteUrl()
        </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>_numEntries</code>.
        </p>
        <CODE_SNIPPET>
          class MyClass
          {
          public:
              ...
              int getNumEntries() const { return _numEntries_; }
              void setNumEntries(int numEntries) { _numEntries = numEntries; }

          private:
              int _numEntries;
          };
        </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>
      Namespaces names are named like <A HRED="#Type_Names">types</A>.
      They start with a capital letter and have a capital letter for
      each new word, with no underscores:
      <code>MyNamespace</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 also be named like
      <A HREF="#Type_Names">type names</A>: <code>EnumName</code>.
    </SUMMARY>
    <BODY>
      <p>
        Preferably, the individual enumerators should be named like
        <A HREF="#Macro_Names">macros</A>.
      </p>
      <CODE_SNIPPET>
        enum UrlTableErrors
        {
            OK = 0,
            OUT_OF_MEMORY = 1,
            MALFORMED_INPUT = 2
        };
      </CODE_SNIPPET>

    </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>
    </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 &#8212; the next
    one may be you!
  </p>


  <STYLEPOINT title="Comment Style">
    <SUMMARY>
      For comments inside the implementation use either the <code>//</code>
      or <code>/* */</code> syntax, as long as you are consistent. For header
      file comments use <a href="http://www.stack.nl/~dimitri/doxygen/" target="blank">Doxygen</a>
      <code>///</code> or <code>/** */</code> comments. Doxygen allows to
      automatically generating browsable source code documentation. Additional
      information like a brief description or function parameter description
      can be added inside Doxygen comments with backslashed or @-prefixed
      keywords like <code>/// \brief</code> or <code>/// @see</code>.
    </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 the copyright and license 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>the copyright statement:
                <code>Copyright (c) 2013, OpenGeoSys Community (http://www.opengeosys.net)</code>)</li>
            <li>the statement where to find the OGS license</li>
            <li>the author and an ISO date of the file creation (e.g. 2011-12-31)</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>

        <CODE_SNIPPET>
          /**
           * \file
           * \author [FirstName] [LastName]
           * \date   [FileCreationDate]
           * \brief  A brief description of this file.
           *
           * \copyright
           * Copyright (c) 2013, OpenGeoSys Community (http://www.opengeosys.org)
           *            Distributed under a Modified BSD License.
           *              See accompanying file LICENSE.txt or
           *              http://www.opengeosys.org/project/license
           *
           */
        </CODE_SNIPPET>
      </SUBSECTION>

      <SUBSECTION title="File Contents">
        <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>.cpp</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>.cpp</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>.cpp</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:
         *  \code
         *    GargantuanTableIterator* iter = table-&gt;NewIterator();
         *    for (iter-&gt;Seek("foo"); !iter-&gt;done(); iter-&gt;Next()) {
         *      process(iter-&gt;key(), iter-&gt;value());
         *    }
         *    delete iter;
         *  \endcode
         */
        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>nullptr</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:
           *  \code
           *     Iterator* iter = table-&gt;NewIterator();
           *     iter-&gt;Seek("");
           *     return iter;
           *  \endcode
           *  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>
          /// \brief 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>nullptr</code> or -1, document this.
          For example:
        </p>
        <CODE_SNIPPET>
          private:
           /// \brief 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 _numTotalEntries;
        </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 &lt; result-&gt;size(); i++)
          {
              x = (x &lt;&lt; 8) + (*result)[i];
              (*result)[i] = x &gt;&gt; 1;
              x &amp;= 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.
          mmapBudget = max&lt;int64&gt;(0, mmapBudget - _index-&gt;length());
          if (mmapBudget &gt;= _dataSize &amp;&amp; !MmapData(mmapChunkBytes, mlock))
              return;  // Error already logged.
        </CODE_SNIPPET>
        <p>
          Note that there are both comments that describe what the
          code is doing, and comments that mention that an error has
          already been logged when the function returns.
        </p>
        <p>
          If you have several comments on subsequent lines, it can
          often be more readable to line them up:
        </p>
        <CODE_SNIPPET>
          doSomething();                  // Comment here so the comments line up.
          doSomethingElseThatIsLonger();  // Comment here so there are two spaces between
                                          // the code and the comment.
          {   // One space before comment when opening a new scope is allowed,
              // thus the comment lines up with the following comments and code.
              doSomethingElse();  // Two spaces before line comments normally.
          }
        </CODE_SNIPPET>
      </SUBSECTION>
      <SUBSECTION title="nullptr, true/false, 1, 2, 3...">
        <p>
          When you pass in <code>nullptr</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(interestingValue,
                                            10,
                                            false,
                                            nullptr);  // What are these arguments??
        </BAD_CODE_SNIPPET>
        <p>
          versus:
        </p>
        <CODE_SNIPPET>
          bool success = calculateSomething(interestingValue,
                                            10,     // Default base value.
                                            false,  // Not the first time we're calling this.
                                            nullptr);  // No callback.
        </CODE_SNIPPET>
      </SUBSECTION>

      <SUBSECTION title="Dont's">
        <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>

</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 100 characters
      long.
    </SUMMARY>
    <BODY>
    </BODY>
  </STYLEPOINT>

  <STYLEPOINT title="Spaces vs. Tabs">
    <SUMMARY>
      Use either spaces or tabs. When using spaces indent 4 spaces at a time.
      Be consistent in a file!
    </SUMMARY>
    <BODY>
    </BODY>
  </STYLEPOINT>

  <STYLEPOINT title="Indenting">
    <SUMMARY>
      Use either <a href="http://en.wikipedia.org/wiki/Indent_style#Allman_style">Allman style</a>
      or <a href="http://en.wikipedia.org/wiki/Indent_style#K.26R_style">K&amp;R style</a>
      for bracket indenting. Be consistent in a file!
    </SUMMARY>
    <BODY>
      <p>
        Advantages of the Allman style are that the indented code is clearly
        set apart from the containing statement by lines that are almost
        completely whitespace, improving readability, and the closing brace
        lines up in the same column as the opening brace, making it easy to
        find matching braces
      </p>
      <CODE_SNIPPET>
        if (x == y)
        {
            doSomething();
            doSomethingElse();
        }
      </CODE_SNIPPET>
      <p>
        K&amp;R style is more compact but lacks some clearness.
      </p>
      <CODE_SNIPPET>
        if (x == y) {
            doSomething();
            doSomethingElse();
        }
      </CODE_SNIPPET>
    </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 parName1, Type parName2)
        {
            doSomething();
            ...
        }
      </CODE_SNIPPET>
      <p>
        If you have too much text to fit on one line:
      </p>
      <CODE_SNIPPET>
        ReturnType ClassName::reallyLongFunctionName(Type parName1, Type parName2,
                                                     Type parName3)
        {
            doSomething();
            ...
        }
      </CODE_SNIPPET>
      <p>
        or if you cannot fit even the first parameter:
      </p>
      <CODE_SNIPPET>
        ReturnType LongClassName::reallyReallyReallyLongFunctionName(
            Type parName1,  // 4 space / 1 tab indent
            Type parName2,
            Type parName3)
        {
            doSomething();  // 4 space / 1 tab indent
            ...
        }
      </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 (lopsidedScore)
          {
        #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 (lopsidedScore)
          {
              #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.
    </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:
            MyClass();  // Regular 4 space / 1 tab indent.
            explicit MyClass(int var);
            ~MyClass() {}

            void someFunction();
            void someFunctionThatDoesNothing() {}

            void setSomeVar(int var) { _someVar = var; }
            int getSomeVar() const { return _someVar; }

        private:
            bool someInternalFunction();

            int _someVar;
            int _someOtherVar;
            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 not indented.
             </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> The <code>public</code> section should be first, followed by
             the <code>protected</code> and finally the
             <code>private</code> section.
             </li>
        <li> When using Qt slot definitions should follow the corresponding
             section. So <code>public slots:</code> should follow
             <code>public</code>. The signal definition <code>signals:</code>
             should be placed at the end.
             </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) : _someVar(var), _someOtherVar(var + 1) {}
      </CODE_SNIPPET>
      <p>
        or
      </p>
      <CODE_SNIPPET>
        // When it requires multiple lines put the colon on
        // the first initializer line:
        MyClass::MyClass(int var)
        : some_var_(var),
          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>
        while (test) {}   // There is usually no space inside parentheses.
        switch (i)
        for (int i = 0; i &lt; 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 &lt; 5; ++i )
        for ( ; i &lt; 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 &amp;&amp; !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&lt;string&gt; x;           // No spaces inside the angle
        y = static_cast&lt;char*&gt;(x);  // brackets (&lt; and &gt;), before
                                    // &lt;, or between &gt;( in a cast.
        vector&lt;char *&gt; x;           // Spaces between type and pointer are
                                    // okay, but be consistent.
        set&lt;list&lt;string&gt; &gt; x;       // C++ requires a space in &gt; &gt;.
        set&lt; list&lt;string&gt; &gt; x;      // You may optionally use
                                    // symmetric spacing in &lt; &lt;.
        </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>.cpp</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.cpp</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>

<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 dont's 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>
    Note that this guide is not a C++ tutorial: we assume that the
    reader is familiar with the language.
  </p>
</CATEGORY>

</GUIDE>