codingguide.xml

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
<GUIDE title="STAR C++ Coding Guidelines">
    
    <address>
        Authors:<br/>
        Mustafa Mustafa <br/>
        Thomas Ullrich <br/>
        Anselm Vossen <br/>
    </address>
    
    <address><p><em>Version 1.0, June 24, 2015</em></p></address>
    
    <CATEGORY title="Introduction">
    <p>
        This is a document of the C++ coding guidelines compiled for the STAR
        collaboration by the above mentioned authors. This effort was initiated by the STAR
        computing coordinator Jerome Lauret on October 31, 2014. The charge can be
        viewed <a href="charge.txt">here</a>. The committee produced two documents, one for the
        coding guidelines seen here, and one for the naming and formatting guidelines that
        can be viewed <a href="formatguide.xml">here</a>.
    </p>
    
    <p>
        The committee based their work on the existing guidelines, expanded them for clarity, and
        added new material where it saw fit. The coding guidelines include the new C++11 standard.
        We have made heavy use of the C++ Google Style guide at <a href="http://google-styleguide.googlecode.com">
        http://google-styleguide.googlecode.com</a> using their xml and css style sheets.
    </p>

    <p>
        The goal of this guide is to manage the complexity of C++ (often in conjunction with ROOT)
        by describing
        in detail the dos and don'ts of writing C++ code. These rules exist to
        keep the STAR code base manageable while still allowing coders to use C++ language
        features productively. In some cases
        we constrain, or even ban, the use of certain C++ and ROOT features. We do this to
        keep code simple and to avoid the various common errors and
        problems that these features can cause. We also had to take into account that
        millions of lines of STAR code exist. For a new experiment the guidelines certainly
        would look different in places but we have to live with the legacy
        of existing code and the guidelines under which they were written.
    </p>
    
    <p>
        Note that this guide is not a C++ tutorial: we assume that the
        reader is familiar with the language. We marked parts of the guidelines that address
        specifically new C++11 features.
    </p>
 
    </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. The first level of hidden information is
                    the subsection <i>Summary</i> in each rule and the second level of hidden information is the
                    optional subsection <i>Extra details and exceptions to the rule</i>. Click the arrow on the
                    left now, you should see "Hooray" appear below.
                </SUMMARY>
                <BODY>
                    <p>
                        Hooray!  Now you know you can expand points to get more
                        details.  Alternatively, there are an "expand all summaries"
                        and an "expand all summaries and extra details" at the
                        top of this document.
                    </p>
                </BODY>
            </STYLEPOINT>
        </CATEGORY>
        
    </OVERVIEW>
    
    <CATEGORY title="Header Files">
        <p>
            In general, every <code>.cxx</code> file should have an associated
            <code>.h</code> file. Each header file should contain only one or related class declarations for maintainability and for easier retrieval of class definitions.
        </p>
        <p>
            Correct use of header files can make a huge difference to the
            readability, size and performance of your code.
            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;FILE&gt;</i>_H</code>.
            </SUMMARY>
            <BODY>
                
                <p>
                    For example, the file
                    <code>myFile.h</code> should
                    have the following guard:
                </p>
                <CODE_SNIPPET>
                    #ifndef MYFILE_H
                    #define MYFILE_H
                    
                    ...
                    
                    #endif  // MYFILE_H
                </CODE_SNIPPET>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Forward Declarations">
            <SUMMARY>
                You may forward declare ordinary classes in order to avoid
                unnecessary <code>#include</code>s.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    A "forward declaration" is a declaration of a class, function,
                    or template without an associated definition. <code>#include</code>
                    lines can often be replaced with forward declarations of whatever
                    symbols are actually used by the client code.
                </DEFINITION>
                <PROS>
                    <ul>
                        <li>Unnecessary <code>#include</code>s force the compiler to open
                            more files and process more input.</li>
                        <li>They can also force your code to be recompiled more often, due
                            to changes in the header.</li>
                    </ul>
                </PROS>
                <CONS>
                    <ul>
                        <li>It can be difficult to determine the correct form of a
                            forward declaration in the presence of features like templates,
                            typedefs, default parameters, and using declarations.</li>
                        <li>Forward declaring multiple symbols from a header can be more
                            verbose than simply including the header.</li>
                        <li>Forward declarations of functions and templates can prevent
                            the header owners from making otherwise-compatible changes to
                            their APIs; for example, widening a parameter type, or adding
                            a template parameter with a default value.</li>
                        <li>Forward declaring symbols from namespace <code>std::</code>
                            usually yields undefined behavior.</li>
                    </ul>
                </CONS>
                <DECISION>
                    <ul>
                        <li>When using a function declared in a header file, always
                            <code>#include</code> that header.</li>
                        <li>When using a class template, prefer to <code>#include</code> its
                            header file.</li>
                        <li>When using an ordinary class, relying on a forward declaration
                            is OK, but be wary of situations where a forward declaration may
                            be insufficient or incorrect; when in doubt, just
                            <code>#include</code> the appropriate header.</li>
                        <li>Do not replace data members with pointers just to avoid an
                            <code>#include</code>.</li>
                    </ul>
                    Always <code>#include</code> the file that actually provides the
                    declarations/definitions you need; do not rely on the symbol being
                    brought in transitively via headers not directly included. One
                    exception is that <code>myFile.cxx</code> may rely on
                    <code>#include</code>s and forward declarations from its corresponding
                    header file <code>myFile.h</code>.
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Inline Functions">
            <SUMMARY>
                As a general rule, put function definitions into the <code>.cxx</code> file.
                Short, compact member functions can be put in the header file <em>after</em> the class declaration
                preceded by the <code>inline</code> keyword. Inlining virtual function is discouraged.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    <p>
                        The inline keyword indicates that inline substitution of the function body at the point
                        of call is to be preferred to the usual function call mechanism.
                        But a compiler is not required to perform this inline substitution at the point of call.
                    </p>
                </DEFINITION>
                <SUBSECTION title="Discussion:">
                    <p>
                        Functions that are defined within a class definition are implicitly inline. Note, however, that the definition of functions in the class definition is strongly discouraged in STAR.
                    </p>
                    <p>
                        An inline function must be defined in every translation unit from where it is called.
                        It is undefined behavior if the definition of the inline function is not the same for all translation units.
                        Note that this implies that the function is defined in a header file.
                        This can have an impact on compile time and lead to longer (= less efficient) development cycles.
                    </p>
                    <p>
                        Note that the inline keyword has no effect on the linkage of a function.
                        Linkage can be changed via unnamed namespaces or the static keyword.
                    </p>
                    <p>
                        In general, virtual functions can only be inlined when the compiler can either prove that the static
                        type matches the dynamic type or when the compiler can safely determine the dynamic type. For example,
                        when you use a value of type A the compiler knows that the dynamic type cannot be different and it can
                        inline the function. When using a pointer or a reference the compiler generally cannot prove that the
                        static type is the same and virtual functions generally need to follow the usual virtual dispatch.
                    </p>
                    </SUBSECTION>
                <DECISION>
                    <p>
                        If you add a new function, put it into the <code>.cxx</code> file per default.
                        Small functions, like accessors and mutators may be placed into the <code>.h</code> file instead (<code>inline</code>).
                        Also, most template function implementations need to go into the <code>.h</code> file.
                        If you later determine that a function should be moved from the <code>.cxx</code> file into the <code>.h</code> file, please make sure that it helps the compiler in optimizing the code.
                        Otherwise you're just increasing compile time.
                    </p>
                    <p>
                       The inlining of virtual functions is problematic. At least one virtual function must be outlined but we
                       advise to not inline virtual functions as a general rule.
                       This pins the vtable, which will otherwise cause a pile of unnecessary symbols.
                    </p>
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Names and Order of Includes">
            <SUMMARY>
                Include headers from external libraries using <b>angle brackets</b>. Include headers from your own project/libraries using <b>double quotes</b>.<br/>
                Do not rely on implicit includes. Make header files self-sufficient. <br/>
            </SUMMARY>
            <BODY>
                <p>
                    There are two types of #include statements: <code>#include &lt;myFile.h&gt;</code> and <code>#include “myFile.h”</code>.
                </p>
                <ul>
                    <li> Include headers from external libraries using angle brackets.
                        <CODE_SNIPPET>
                            #include &lt;iostream&gt;
                            #include &lt;cmath&gt;
                            #include &lt;TH1D.h&gt;
                        </CODE_SNIPPET>
                    </li>
                    <li>
                        Include headers from your own project or any STAR related project using double quotes.
                        <CODE_SNIPPET>
                            #include &quot;MyClass.h&quot;
                            #include &quot;StEnumeration.h&quot;
                        </CODE_SNIPPET>
                    </li>
                </ul>
                <p>
                    The header files of external libraries are obviously not in the
                    same directory as your source files. So you need to use angle brackets.
                </p>
                <p>
                    Headers of your own application have a defined relative location to the source
                    files of your application. Using double quotes, you have to specify the correct
                    relative path to the include file.
                </p>
                
                <i>Include order </i>
                <p>
                    Another important aspect of include management is the include order.
                    Typically, you have a class named Foo, a file Foo.h and a file Foo.cxx .
                    The rule is&#160;:
                    In your file Foo.cxx, you should include Foo.h as the first include, before the system
                    includes.
                </p>
                <p>
                    The rationale behind that is to make your header standalone.
                </p>
                <p>
                    Let's imagine that your Foo.h looks like this:
                    <BAD_CODE_SNIPPET>
                        class Foo
                        &#123;
                        public:
                           Bar getBar&#40;&#41;;
                        &#125;;
                    </BAD_CODE_SNIPPET>
                </p>
                <p>
                    And your Foo.cxx looks like this:
                    <BAD_CODE_SNIPPET>
                        #include &quot;Bar.h&quot;
                        #include &quot;Foo.h&quot;
                    </BAD_CODE_SNIPPET>
                </p>
                <p>
                    Your Foo.cxx file will compile, but it will not compile for other people using Foo.h without including Bar.h.
                    Including Foo.h first makes sure that your Foo.h header works for others.
                    <CODE_SNIPPET>
                        // Foo.h
                        #include &quot;Bar.h&quot;
                        class Foo
                        &#123;
                        public:
                           Bar getBar&#40;&#41;;
                        &#125;;
                    </CODE_SNIPPET>
                    
                    <CODE_SNIPPET>
                       // Foo.cxx
                       #include &quot;Foo.h&quot;
                    </CODE_SNIPPET>
                </p>
                <p>
                    For more details: <a href="http://techbase.kde.org/Policies/Library_Code_Policy#Getting_.23includes_right">Getting #includes right</a>.
                </p>
            </BODY>
        </STYLEPOINT>
        
    </CATEGORY>
    
    <CATEGORY title="Namespaces">
        <p>
            Namespaces subdivide the global scope into distinct, named
            scopes, and thus are useful for logically grouping related types and functions and
            preventing name collisions. In C++ it is in general very good practice to use namespaces,
            especially in libraries. However, historically STAR software makes little to no use of namespaces
            but rather uses a specific naming scheme (prefixes) to indicate the scope
            (e.g. <code>StEmc</code>..., <code>StTpc</code>... etc). While certain tools in STAR can handle
            namespaces (such as <code>cons</code>) others would be very cumbersome to adapt.
        </p>
        
        <STYLEPOINT title="General Guideline">
            <SUMMARY>
                Namespaces are for legacy reasons depreciated in STAR. As with every guideline there
                might be exceptions, especially in end user code. However, care should be taken to check for
                possible side effects. Namespaces should be entirely avoided in the context of <code>StEvent</code>.
            </SUMMARY>
            <BODY>
                <p>
                    When using namespaces in end-user parts of your code (e.g. specific analysis code),
                    encapsulate your entire class into the namespace.
                    Nonmember functions that are logically tied to a specific type should be in the same namespace as that type.
                    To make namespace work with <code>cons</code> and ROOT use the STAR specific $NMSPC tag as follows
                    
                    <CODE_SNIPPET>
                    namespace StMyStuff //$NMSPC
                    {
                    
                    class AClass : public TNamed {...};
            
                    class BClass : public TNamed {...};
                    
                    } // namespace StMyStuff
                    </CODE_SNIPPET>
                    This will cause cons to generate a dictionary consistent with ROOT. The tag
                    $NMSPC triggers the namespace inclusion (multiple namespaces can be used but
                    you cannot combine sections
                    with namespace and sections without).
                </p>
            </BODY>
            
        </STYLEPOINT>
        
        <STYLEPOINT title="Using Declarations and Directives">
            <SUMMARY>
                Don't write namespace using declarations or using directives
                in a header file or before an #include.
            </SUMMARY>
            <BODY>
                <p>
                    <CODE_SNIPPET>
                        # include "Bar.h"
                        // OK in .cxx after include statements
                        using namespace Foo;
                        
                        // sometimes a using declaration is preferable, to be precise
                        // about the symbols that get imported
                        using Foo::Type;
                    </CODE_SNIPPET>
                </p>
                <p>
                    <BAD_CODE_SNIPPET>
                        // Forbidden in .h -- This pollutes the namespace.
                        using namespace Foo;
                    </BAD_CODE_SNIPPET>
                </p>
                <EXTRA>
                    The using directive can sometimes be useful in header files to import one namespace into another one.
                    This can effectively hide a namespace from the public interface, similar to what an inline namespace does.
                </EXTRA>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="std Namespace">
            <SUMMARY>
                Do not declare anything in namespace <code>std</code>, not even forward
                declarations of standard library classes. The only exception to this rule is template specialization (see below).  
            </SUMMARY>
            <BODY>
                <MOTIVATION>
                    <p>
                        Declaring entities in namespace <code>std</code> represents undefined behavior,
                        i.e., not portable.  To declare entities from the standard library, include
                        the appropriate header file. One exception to this is template specialization, e.g. <code>std::hash&lt;MyType&gt;</code>
                        needs to be in namespace <code>std</code>.
                    </p>
                </MOTIVATION>
            </BODY>
        </STYLEPOINT>
        
    </CATEGORY>
    
    <CATEGORY title="Scoping">
        
        <STYLEPOINT title="Nonmember and Global Functions" nobutton="yes">
            <SUMMARY>
                Avoid non-member function if possible. If it is a function that applies to several classes of similar type consider 
                making it a member of a base class.
            </SUMMARY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Local Variables">
            <SUMMARY>
                Declare variables as locally as possible.
            </SUMMARY>
            <BODY>
                <MOTIVATION>
                    <p> Variables whose lifetime are longer than necessary have several
                        drawbacks:
                        <ul>
                            <li>They make the code harder to understand and maintain.</li>
                            <li>They can't be always sensibly initialized.</li>
                        </ul>
                    </p>
                </MOTIVATION>
                <EXTRA>
                    <ul>
                        <li>It can be sometimes more efficient to declare a variable (usually of an
                            object type) outside a loop.
                            <p>
                                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; bigNumber; ++i) {
                                   Foo foo;  // My ctor and dtor get called bigNumber times each.
                                   foo.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 foo;  // My ctor and dtor get called once each.
                                for (int i = 0; i &lt; bigNumber; ++i) {
                                   foo.doSomething(i);
                                }
                            </CODE_SNIPPET>
                        </li>
                        <li> This item does not apply to constants, because constants don't add a state.
                        </li>
                    </ul>
                </EXTRA>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Variables Initialization">
            <SUMMARY>
                Always initialize variables.<br/>
            </SUMMARY>
            <BODY>
                <p>
                    Do not separate initialization from declaration, e.g.
                </p>
                <BAD_CODE_SNIPPET>
                    int value;
                    value = function();      // Bad -- initialization separate from declaration.
                </BAD_CODE_SNIPPET>
                <CODE_SNIPPET>
                    int value = function();  // Good -- declaration has initialization.
                </CODE_SNIPPET>
                
                <p>
                    Use a default initial value or ternary operator (?:) to reduce mixing data flow with control
                    flow.
                </p>
                <BAD_CODE_SNIPPET>
                    int speedupFactor;       // Bad: does not initialize variable
                    if (condition) {
                       speedupFactor = NoFactor;
                    }
                    else {
                       speedupFactor = DoubleFactor;
                    }
                </BAD_CODE_SNIPPET>
                <CODE_SNIPPET>
                    int speedupFactor = DoubleFactor; // Good: initializes variable
                    if (condition) {
                       speedupFactor = NoFactor;
                    }
                </CODE_SNIPPET>
                <CODE_SNIPPET>
                    int speedupFactor = condition ? NoFactor : DoubleFactor; // Good: initializes variable
                </CODE_SNIPPET>
                
                <p>
                    Prefer declaration of loop variables inside a loop, e.g.
                </p>
                <BAD_CODE_SNIPPET>
                    int i;                   // Bad: does not initialize variable
                    for (i = 0; i &lt; number; ++i) {
                       doSomething(i);
                    }
                </BAD_CODE_SNIPPET>
                <CODE_SNIPPET>
                    for (int i = 0; i &lt; number; ++i) {
                       doSomething(i); // Good
                    }
                </CODE_SNIPPET>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Brace Initialization" cpp11="yes">
            <SUMMARY>
              Prefer initialization with braces except for single-argument assignment. However, never use brace initialization with <code>auto</code>.
            </SUMMARY>
            <BODY>
                <p>In C++11, the brace initialization syntax for builtin arrays and POD structures has been extended for use with all other datatypes.
                    <p> Example of brace initialization:
                    </p>
                    <CODE_SNIPPET>
                        std::vector&#60;std::string&#62; myVector{"alpha", "beta", "gamma"};
                    </CODE_SNIPPET>
                </p>
                <p>
                    Example of single-argument assignments:
                </p>
                <CODE_SNIPPET>
                    int value = 3;                           // preferred style
                    std::string name = "Some Name";
                    
                    int value { 3 };                         // also possible
                    std::string name{ "Some Name" };
                    std::string name = { "Some Name" };
                </CODE_SNIPPET>

                <p>
                  Brace initialization can be in particular useful to initialize class members.
                </p>

                <p>User data types can also define constructors that take
                    <code>initializer_list</code>, which is automatically created from
                    <i>braced-init-list</i>:
                    <CODE_SNIPPET>
                        #include &lt;initializer_list&gt;

                        class MyType
                        {
                        public:
                           // initializer_list is a reference to the underlying init list,
                           // so it can be passed by value.
                           MyType(std::initializer_list&lt;int&gt; initList) {
                              for (int element : initList) {...}
                           }
                        };

                        MyType myObject{2, 3, 5, 7};
                    </CODE_SNIPPET></p>
                
                <p>Finally, brace initialization can also call ordinary constructors of
                    data types that do not have <code>initializer_list</code> constructors.
                    <CODE_SNIPPET>
                        // Calls ordinary constructor as long as MyOtherType has no
                        // initializer_list constructor.
                        class MyOtherType {
                        public:
                           explicit MyOtherType(std::string name);
                           MyOtherType(int value, std::string name);
                        };

                        MyOtherType object1 = {1, "b"};

                        // If the constructor is explicit, you can't use the "= {}" form.
                        MyOtherType object2{"b"};
                    </CODE_SNIPPET></p>
                
                    <p>Never assign a <i>braced-init-list</i> to an <code>auto</code> local variable.</p>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Global Variables">
            <SUMMARY>
                Variables declared in the global scope are not allowed.  Other global variables, including
                static class variables and variables in namespace scope, should be
                avoided where other means of communication are possible.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    A global variable is a variable that can be accessed (theoretically) from everywhere in the program.
                    The adjective "global" should rather be understood as concerning its linkage, not whether it is in the global scope.
                    <BAD_CODE_SNIPPET>
                        int gBar;           // this is obviously global
                        class Something
                        {
                        private:
                           static int sId; // but this one too (details at the end of the rule)
                        };
                        namespace NotGlobalScope {
                        Foo fooObject;    // and finally this one as well
                        }
                    </BAD_CODE_SNIPPET>
                </DEFINITION>
                <PROS>
                    Global variables are a simple solution to sharing of data.
                </PROS>
                <CONS>
                    Global variables make it harder to reason about the code (for humans and compilers):
                    the smaller the number of variables a given region of code reads and writes, the easier.
                    Global variables can be read and written from anywhere.
                    Therefore, global variables pose a challenge to the optimizer.
                </CONS>
                <DECISION>
                    We want to reduce the shared data in our software to the unavoidable minimum.
                    Therefore, global variables should be avoided where other means of communication are possible.
                </DECISION>
                <EXTRA>
                    Note that a private static class variable sId is global. For example two threads having
                    each an instance of the class could access sId via these instances.
                </EXTRA>
            </BODY>
        </STYLEPOINT>
        <STYLEPOINT title="Global Variables Initialization">
            <SUMMARY>
                In the rare and justified cases where you use global variables, including file-static variables, static member variables and variables in
                namespace scope, initialize them statically.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    <ul>
                        <li>This rule additionally applies to file-static variables.</li>
                        <li>A global variable is statically initialized if the type has no constructor or a <code>constexpr</code> constructor.
                            This is the case for fundamental types (integers, chars, floats, or pointers) and POD (Plain Old Data: structs/unions/arrays
                            of fundamental types or other POD structs/unions). </li>
                    </ul>
                </DEFINITION>
                <PROS>
                    Dynamic initialization of globals can be used to run code before <code>main()</code>.
                    Destructors of globals can be used to run code after <code>main()</code>.
                    Dynamic initialization of globals in dynamically loaded objects can be used to run code on plugin load.
                </PROS>
                <CONS>
                    It is very hard to reason about the order of execution of such functions.
                    Especially if dynamically initialized globals are present in shared libraries that are linked
                    into dynamically loaded objects, few people understand the semantics.
                </CONS>
                <p>
                    As an example do this:
                </p>
                <CODE_SNIPPET>
                    struct Pod {
                       int indexes[5];
                       float width;
                    };
                    struct LiteralType {
                       int value;
                       constexpr LiteralType() : value(1) {}
                    };
                    
                    Pod gData;
                    LiteralType gOtherData;
                </CODE_SNIPPET>
                <p>
                    But not this :
                </p>
                <BAD_CODE_SNIPPET>
                    class NotPod {
                       NotPod();
                    };
                    NotPod gBadData;  // dynamic constructor
                </BAD_CODE_SNIPPET>
                <!--
                 // a.cxx:
                 int gSomeValue = someFunction();
                 
                 // b.cxx:
                 extern int gSomeValue;
                 int someOtherFunction() { return gSomeValue + 1; }
                 int gGlobalValue = someOtherFunction(); // it is undefined whether gGlobalValue
                 // will be 0 + 1 or someFunction() + 1
                 -->
                <DECISION>
                    Global variables must be initialized statically. <br/>
                    We only allow global variables to contain POD data.  This
                    rule completely disallows <code>std::vector</code> (use <code>std::array</code> instead), or
                    <code>std::string</code> (use <code>const char []</code>) for global variables.
                </DECISION>
                <EXTRA>
                    <p>
                        If there is a need for startup or shutdown code, dynamic constructors may be used. But only if:
                        <ul>
                            <li>The dependencies on other data are minimized.</li>
                            <li>It is documented what code depends on this and why there is no issue of incorrect calling order.</li>
                            <li>Side-effects are clearly understood and documented.</li>
                        </ul>
                    </p>
                    <p>
                        Example that exhibits the problem of execution order:
                    </p>
                    <BAD_CODE_SNIPPET>
                        // Struct.h:
                        #include &lt;string&gt;
                        struct Struct {
                           static std::string sString;
                        };
                        
                        // Struct.cxx:
                        std::string Struct::sString = "Hello World";
                        
                        // main.cxx:
                        #include "Struct.h"
                        #include &lt;iostream&gt;
                        
                        std::string gAnotherString = Struct::sString;
                        
                        int main() {
                           std::cout &lt;&lt; gAnotherString &lt;&lt; std::endl;
                           return 0;
                        }
                    </BAD_CODE_SNIPPET>
                    <p>
                        This program will either output "Hello World" or crash, depending on the initialization order (with GCC on Linux it depends on whether you link with <code>g++ Struct.o main.o</code> or <code>g++ main.o Struct.o</code>).
                    </p>
                </EXTRA>
                
            </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="Constructors">
            <SUMMARY>
                Every class should have at least one constructor. All uninitialized variables should be initialized in the constructor.
            </SUMMARY>
            <BODY>
                <p>Every class should have at least one constructor
                  even if it does nothing or is defined to do nothing, or compiler defaults should be <em>explicitly</em>
                  requested using the <code>default</code> specifier. This is good practice, it indicates to
                the reader that the coder thought about this and not plainly forgot about it.</p>
                
                <p>If a class does not have a constructor there is no guarantee of
                how objects of that class will be initialized, whilst data members should be explicitly initialized therein. When
                the constructor dynamically allocates memory, a destructor must be added to return the memory to the free pool
                when an object gets cleaned up.</p>
                
                In the constructor all data member should be initialized, either in the constructor function body or in the constructor initializer list
                or in-class. See the next item for more.
            </BODY>
        </STYLEPOINT>
       
        <STYLEPOINT title="Initialization">
            <SUMMARY>
                Declare and initialize members variables in the same order.
                Prefer initialization (in the constructor initializer list or in-class) to assignment (in the constructor function body).
            </SUMMARY>
            <BODY>
                <CPP11 title="In-Class Member Initialization">
                    C++98 allows in-class member initialization for const static members only. C++11 allows in-class member initialization for any variable.
                    <CODE_SNIPPET>
                    class MyClass
                    {
                    public:
                       int x = 1;
                    };
                    </CODE_SNIPPET>
                    This is basically equivalent to using initialization lists in constructors. The advantage of in-class initialization is that it allows
                    consistent default initialization when there are multiple constructors and saves a lot of typing resulting in cleaner codes.  
                    
                    Constructor initialization overrides in-class initialization.
                </CPP11>
                
                <DEFINITION>
                    <p>
                        Class member variables are initialized in the order in which they are declared in the class definition.
                        The order in the constructor initializer list has no influence on initialization order and therefore may be misleading if it does not match the order of the declaration.
                        Compilers often issue a warning if this rule is broken, but not always.
                    </p>
                    <p>
                        If a member variable is not explicitly initialized in the constructor initializer list and it is a non-POD the default constructor of that variable is called. 
                        Therefore, if a member variable is assigned to in the constructor function body, the member variable may get initialized unnecessarily with the default constructor.
                        If the variable is a POD and the class instance is created with the <code>new</code> operator the variable will be zero-initialized. Otherwise, PODs are left uninitialized
                        see examples below.

                    </p>
                    <p>
                        If you do not declare any constructors yourself then the compiler will generate a
                        default constructor for you, which may leave some fields uninitialized or
                        initialized to inappropriate values.
                    </p>
                    <p>
                        Examples:
                    </p>
                    <p>
                        Initialization list:
                    </p>
                    <CODE_SNIPPET>
                        // MyClass.h
                        class MyClass : public MyBase  {
                        // ...
                        private:
                           int mValue;
                           std::vector mVector;
                        };

                        // MyClass.cxx
                        MyClass::MyClass() : MyBase(),
                           mValue(0),
                           mVector()
                        {}
                    </CODE_SNIPPET>
                    <p>
                        See an example of initialization via <code>std::initializer_list</code>
                        in <a href="#Brace_Initialization"> Brace Initialization</a>.
                    </p>
                    <p>
                        Non explicit initialization:
                    </p>
                    <CODE_SNIPPET>
                        struct MyStruct
                        {
                           int x;
                           myStruct(): x(10) {}
                        };
                        
                        class MyClass
                        {
                        public:
                           int mX;
                           int mY;
                           MyStruct mS;
                        
                           // mS and mY are not explicitly initialized in the initializer list
                           // mS default constructor will always be called.
                           // mY is a POD therefore it will be:
                           //    Zero-initialized if instance of MyClass is created with new operator.
                           //    Otherwise, left un-initialized.
                           MyClass(): mX(5) { cout &lt;&lt; mX &lt;&lt; " " &lt;&lt; mS.x &lt;&lt; " " &lt;&lt; mY &lt;&lt; endl; }
                        };
                        
                        int main()
                        {
                           MyClass c0; // MyClass::mY will not be initialized.
                           MyClass* c1 = new MyClass(); // MyClass::mY will be zero-initialized.
                           MyClass* c2 = new MyClass;   // MyClass::mY will be zero-initialized.
                        }
                    </CODE_SNIPPET>
                </DEFINITION>
                
                <DECISION>
                    <p>
                        Member variables should be declared and initialized in the same order.
                    </p>
                    <p>
                        Use in-class member initialization for simple initializations,
                        especially when a member variable must be initialized the same way
                        in more than one constructor.
                    </p>
                    <p>
                        If your class defines member variables that aren't
                        initialized in-class, and if it 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>
                        If your class inherits from an existing class but you add no
                        new member variables, you are not required to have a default
                        constructor, also see <a href="#Delegating_and_Inheriting_Constructors">Delegating and Inheriting Constructors</a>.
                    </p>
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Virtual Functions in Constructors and Destructors">
            <SUMMARY>
                Do not call virtual functions in constructors and destructors. <br/>
            </SUMMARY>
            <BODY>
                
                <p>
                    Inside constructors and destructors virtual function do not
                    behave "virtually". If the work calls virtual functions, these calls
                    will not get dispatched to the subclass implementations.
                    Calls to an unimplemented pure virtual function result in undefined
                    behavior.
                </p>
                <p>
                    Calling a virtual function non-virtually is fine:
                    <BAD_CODE_SNIPPET>
                        class MyClass {
                        public:
                           MyClass() { doSomething(); }    // Bad
                           virtual void doSomething();
                        };
                    </BAD_CODE_SNIPPET>
                    <CODE_SNIPPET>
                        class MyClass {
                        public:
                           MyClass() { MyClass::doSomething(); }    // Good
                           virtual void doSomething();
                        };
                    </CODE_SNIPPET>
                </p>
                <DECISION>
                    Constructors should never call virtual functions.
                </DECISION>
            </BODY>
        </STYLEPOINT>
    
        <STYLEPOINT title="Copy Constructor and Assignment Operator">
          <SUMMARY>
            Each class should have an assignment operator and a copy constructor implemented or explicitly deleted. Exception is when the class doesn't allocate subsidiary
            data structures on the heap, in this case compiler defaults can be explicitly requested. Be aware of data slicing for polymorphic classes.
          </SUMMARY>
          <BODY>

            <CPP11 title="Control of Defaults: default and delete">
              Since C++11, the programmer can instruct the compiler not to create certain defaults by using the specifier <code>= delete</code>
              This is particularly useful in two cases: 

              1) Making objects non-copyable:  

              <CODE_SNIPPET>
                class NonCopyable 
                {
                   NonCopyable(const NonCopyable&amp;) = delete;
                   NonCopyable&amp; operator=(const NonCopyable&amp;) = delete;
                };
              </CODE_SNIPPET>

              2) Preventing implicit conversion of function arguments:  

              <CODE_SNIPPET>
                class MyClass
                {
                   void f(double i);
                   void f(int) = delete;
                };
              </CODE_SNIPPET>

              The specifier <code>= default</code> can be used to state the programmers wish for defaults to be created.

              <CODE_SNIPPET>
                class MyClass
                {
                   MyClass() = default; // default constructor is explicitly requested.
                   MyClass(...);
                };
              </CODE_SNIPPET>

              However, the verbosity here is redundant, it is useful as a declaration of intention.  

              For classes, the default generated functions are always public. Programmer can control the 
              visibility of the defaults by using <code>= default</code>.
            </CPP11>

            <DEFINITION>
              The copy constructor and copy assignment operator are used to create copies of objects.

              <p>
                The assignment operator
                <CODE_SNIPPET>
                  ClassName&amp; operator=(const ClassName&amp;)
                </CODE_SNIPPET>

                is called when one instance of a class is assigned to another.
                The copy constructor
                <CODE_SNIPPET>
                  ClassName(const ClassName&amp;)
                </CODE_SNIPPET>


                defines the behavior of the class when it is passed by value as an argument, returned by
                value from a function, or used to initialize one instance with the value of another class instance. Defining this
                constructor, all the class objects are copied properly.
              </p>

              <p>It is possible to implement  one using the other. One can safely invoke the copy assignment operator 
                from the constructor as long as the operator is not declared virtual.</p>

                                  <SUBSECTION title="The Rule of Three">
                      <p>
                        The rule of three is a rule of thumb in C++ that claims that if a class defines one of the following it should probably explicitly define all three:
                        <ul>
                          <li>destructor</li>
                          <li>copy constructor</li>
                          <li>copy assignment operator</li>
                        </ul>
                        The Rule of Three claims that if one of these had to be defined by the programmer, it means that the compiler-generated version does not fit 
                        the needs of the class in one case and it will probably not fit in the other cases either.</p>
                    </SUBSECTION>
                  </DEFINITION>

                  <DECISION>
                    Most classes that allocate subsidiary data structures on the heap or consume any other kind of shared resources
                    should have a copy constructor and assignment operator.

                    <p>Exception 1: do not implement your own copy/assignment when member-wise copy is desired and request the compiler to generate the defaults instead. For example, use:
                      <CODE_SNIPPET>
                        ClassName(const ClassName &amp;other) = default;
                        ClassName&amp; operator=(const ClassName&amp;) = default;
                      </CODE_SNIPPET>
                      instead of
                      <BAD_CODE_SNIPPET>
                        ClassName(const ClassName &amp;other): data(other.data) {}
                        ClassName&amp; operator=(const ClassName &amp;other): data(other.data) {}
                      </BAD_CODE_SNIPPET>
                      The former can be optimized much better by the compiler.
                    </p>

                    <p>Exception 2: if the design of the class specifically demands that no copy is created (e.g. for singletons) the copy constructor and assignment 
                      operators should be disabled by using the <code>delete</code> keyword (C++11) or by making them private (C++98 or older). </p>

                    <p>
                      Polymorphic class design implies pointer semantics. Since copy constructors/assignment operators, etc. cannot be made virtual, making a base class copyable
                      could result in objects slicing.
                    </p>
                    <p>
                        If your polymorphic class needs to be copyable, consider using a virtual <code>clone()</code> method.
                        This way copying can be implemented without slicing and be used more naturally for pointers:
                        <CODE_SNIPPET>
                        void someFunction(SomeInterface *object)
                        {
                           SomeInterface *objectCopy = object->clone();
                           ...
                        }
                        </CODE_SNIPPET>
                    </p>

                  </DECISION>
          </BODY>
    </STYLEPOINT>


        <STYLEPOINT title="Move Constructor and Assignment Operator" cpp11="yes">
            <SUMMARY>
                Only implement move constructors/assignment operators if your class needs optimizations for move semantics.
            </SUMMARY>
            <BODY>
                <CPP11 title="Rule of Five">
                  Control of defaults can be used for copy/move assignment operators or constructors and destructor.
                  However, one should pay attention to the <a href="http://en.wikipedia.org/wiki/Rule_of_three_%28C%2B%2B_programming%29#Rule_of_5">Rule of Five</a>.
                  Stated roughly by <a href="http://www.stroustrup.com/C++11FAQ.html">Stroustrup</a>:

                  <p>
                    1) If any move, copy, or destructor is explicitly specified (declared, defined, =default, or =delete) by the user, no move is generated by default.   
                  </p>
                  <p>
                    2) If any move, copy, or destructor is explicitly specified (declared, defined, =default, or =delete) by the user, any undeclared copy operations 
                    are generated by default, but this is deprecated, so don't rely on that.
                  </p>
                </CPP11>

                <DEFINITION>
                  The move constructor and move assignment operator are used to move (semantically) objects. Move semantics were introduced with C++11.
                  In essence, a move is just a copy that can be optimized from the knowledge that the source object is at the end of its life (such objects bind to rvalue references).
                  Thus, a move of a <code>std::vector</code> does not need to copy all data, but only the pointer to the data.
                  Additionally, the source object must be told that it does not own the data anymore, to inhibit the <code>free</code> from the destructor.
                  In most cases the move constructor/assignment operator therefore modifies the source object (e.g. setting the data pointer to <code>nullptr</code>).
                  See <a href="#Rvalue_Reference_and_Move_Semantics">rvalue reference and move semantics</a> for more details on move semantics implementation.
                </DEFINITION>

                <DECISION>
                    <p>
                      Only implement move constructors/assignment operators if your class needs optimizations for move semantics.
                    </p>
                  </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Delegating and Inheriting Constructors" cpp11="yes">
            <SUMMARY>
                Use delegating and inheriting constructors when they reduce code duplication. Be aware of self delegation.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    <p>
                        Delegating and inheriting constructors are two different features,
                        both introduced in C++11, for reducing code duplication in
                        constructors. Delegating constructors allow the constructor
                        to forward work to another constructor of the same class,
                        using a special variant of the initialization list
                        syntax.
                    </p>
                    </DEFINITION>
                    <SUBSECTION title="Delegating Constructors">
                        <p>Many classes have multiple constructors, especially in STAR. Often, an empty constructor
                        sets variables to either 0 or any default parameters, while the non-empty constructors are
                        used to set the data member to the values provided. Other examples are constructors that take
                        different arguments, depending on the context the class is used. Often only parts of all data
                        that defined in the class are known at construction time.</p>
                        
                        <p>In many cases this requires to either write constructors with semi-identical code making
                            code maintenance difficult, or providing a private <code>init()</code> function that is called
                            internally by the various constructors.</p>
                        
                        Here’s an example how it was done in C++98:
                        
                        <CODE_SNIPPET>
                        class A {
                        public:
                           A(): num1(0), num2(0) {average=(num1+num2)/2.;}
                           A(int i): num1(i), num2(0) {average=(num1+num2)/2.;}
                           A(int i, int j): num1(i), num2(j) {average=(num1+num2)/2.;}
                        private:
                           int num1;
                           int num2;
                           double average;
                        };
                        </CODE_SNIPPET>
                       
                        To at least keep the repetitions at a minimum often this is done:
                        
                        <CODE_SNIPPET>
                        class A {
                        public:
                           A(): num1(0), num2(0) {init();}
                           A(int i): num1(i), num2(0) {init();}
                           A(int i, int j): num1(i), num2(j) {init();}
                        private:
                           int num1;
                           int num2;
                           double average;
                           void init(){ average=(num1+num2)/2.;};
                        };
                        </CODE_SNIPPET>
                        
                        <p>This revision eliminates code duplication but it brings the following new problems:
                        Other member functions might accidentally call <code>init()</code>, which causes unexpected results.
                        After we enter a class member function,  all the class members have already been constructed.
                        It's too late to call member functions to do the construction work of class members.
                        In other words, <code>init()</code> merely reassigns new values to data members.
                        It doesn’t really initialize them.</p>
                        
                        Verbosity hinders readability and repetition is error-prone. Both get in the way of maintainability.
                        So, in C++11, we can define one constructor in terms of another:
                        
                        <CODE_SNIPPET>
                        class A {
                        public:
                           A(): A(0){}
                           A(int i): A(i, 0){}
                           A(int i, int j) {
                              num1=i;
                              num2=j;
                              average=(num1+num2)/2.;
                           }
                        private:
                           int num1;
                           int num2;
                           double average;
                        };
                        </CODE_SNIPPET>
                        
                        <p>Delegating constructors make the program clear and simple. Delegating and target constructors do
                            not need special labels or disposals to be delegating or target constructors. They have the same
                            interfaces as other constructors. A delegating constructor can be the target constructor of another
                            delegating constructor,  forming a delegating chain. Target constructors are chosen by overload
                            resolution or template argument deduction. In the delegating process, delegating constructors
                            get control back and do individual operations after their target constructors exit.</p>
                        
                        <CONS>
                        If not careful one can generate a constructor that delegates to itself:
                        <BAD_CODE_SNIPPET>
                        class C
                        {
                        public:
                           C(int) { }
                           C() : C(42) { }
                           C(char) : C(42.0) { }
                           C(double) : C('a') { }
                        };
                        
                        int main()
                        {
                           C c('b');
                           return 0;
                        }
                        </BAD_CODE_SNIPPET>
                        Different compilers handle this case differently. For example,
                        <code>clang</code> submits an error, <code>gcc</code> compiles and crashes with stack overflow.
                        </CONS>
                        
                        <em>Note that above code is attached to the class definition only for demonstration purposes. In STAR, the use of code in class declarations is strongly discouraged since it reduces readability.</em>
                    </SUBSECTION>
                    <SUBSECTION title="Inheriting Constructors">
                    <p>
                        A derived class, per default, inherits all functions of the base class.
                        This is not the case for constructors.
                        Since C++11 it is possible to explicitly inherit the constructors of a base class.
                        This can be a significant simplification for derived classes that don't need custom constructor logic.
                    </p>
                    <CODE_SNIPPET>
                        class Base {
                        public:
                           Base();
                           Base(int number);
                           Base(const string&amp; name);
                           ...
                        };
                        
                        class Derived : public Base {
                        public:
                           using Base::Base;  // Base's constructors are redeclared here.
                        };
                    </CODE_SNIPPET>
                    <p>
                        This is especially useful when <code>Derived</code>'s constructors
                        don't have to do anything more than calling <code>Base</code>'s
                        constructors.
                    </p>
                    </SUBSECTION>

                <DECISION>
                    <p>
                        Use delegating and inheriting constructors when they reduce code duplication.<br/>
                        Be cautious about inheriting constructors when your derived class has new member
                        variables and use in-class member initialization for the derived class's member variables.
                        When coding delegating constructors be aware of self delegation.
                    </p>
                </DECISION>
            </BODY>
        </STYLEPOINT>

        <STYLEPOINT title="Destructors">
            <SUMMARY>
                Every class must have a destructor defined to free resources (objects, IO handlers, etc.) it allocated during its lifetime
                or compiler defaults should be <em>explicitly</em> requested using the <code>default</code> specifier.
                The base class destructors must be declared virtual if they are public. 
            </SUMMARY>
            
            <BODY>
                <p>
                    By the Rule-of-Five, having a destructor defined or the compiler default explicitly requested will guarantee
                    that the move constructor and assignment operator will not be generated by default (<a href="#Move_Constructor_and_Assignment_Operator">see Rule-of-Five</a>). 
                    It is important for STAR not to have the move semantics generated by the compiler unless explicitly requested.
                    Also to always have a destructor is good practice, it indicates to the reader that the coder thought 
                    about this and not plainly forgot about it.
                </p>
                <p>
                    In polymorphic design a special care is needed in implementing
                    base class destructors. If deletion through a pointer to a base
                    <code>Base</code> should be allowed, then the <code>Base</code>
                    destructor must be public and virtual. Otherwise, it should be
                    protected and can be non-virtual.
                </p>

                <DECISION>
                  <p>
                    Every class must have a destructor defined to free resources (objects, IO handlers, etc.) it allocated during its lifetime
                    or compiler defaults should be <em>explicitly</em> requested using the <code>default</code> specifier.
                    The base class destructors must be declared virtual if they are public. 
                  </p>
                </DECISION>
                <EXTRA>
                    In some class designs the destructors (of all classes in the inheritance tree) do nothing (implying that the classes and their members never allocate any resources).
                    Typically, such designs do not have any virtual functions at all, and the virtual destructor would be the only reason for the existence of a vtable.
                    Then a virtual destructor may be unnecessary and may be omitted.
                </EXTRA>
            </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>
              <DEFINITION>
                <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>
              </DEFINITION>
              <DECISION>
                <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.
                </p>
                <p>
                    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>
              </DECISION>
            </BODY>
        </STYLEPOINT>
        
        
        <STYLEPOINT title="Inheritance">
            <SUMMARY>
                When using inheritance, make it <code>public</code> and declare overridden methods
                as <code>override</code> or <code>final</code>.
                However, composition is often more appropriate than inheritance especially if a
                class is not designed to be a base class.
            </SUMMARY>
            <BODY>
                <CPP11 title="Override Controls: override and final">
                    <p>
                      Since C++11 it is possible to mark virtual methods as overriding a virtual methods from the base class using the keyword <code>override</code>.

                      This is useful to state the intent and get a compile error (on otherwise silent errors) if this intent is not fulfilled for some reason 
                      (e.g. typo in the method name, mismatching method signature, virtual keyword forgotten in the base class).
                      For example:
                      <CODE_SNIPPET>
                      class Base
                      {
                         virtual void a(int);
                         virtual void f();
                         virtual void g() const;
                         void k(); // not virtual
                         virtual void h(char);
                      };
                      
                      class Derived : public Base
                      {
                         void a(float) override; // doesn't override Base::a(int) (wrong signature)
                         void f() override; // overrides Base::f()
                         void g() override; // doesn't override Base::g() (wrong type)
                         void k() override; // doesn't override Base::k() (Base::k() is not virtual)
                         void h(char); // overrides Base::h()
                      };
                      </CODE_SNIPPET>
                      
                      Error given by gcc compiler when there is a problem with an override attempt is  
                      
                      <CODE_SNIPPET>
                      error: ‘void foo::foo()’ marked override, but does not override.
                      </CODE_SNIPPET>
                    </p>

                    <p>
                      The <code>final</code> keyword tells the compiler that derived classes may not override the virtual methods anymore.
                      This is useful to limit abuse of your classes by users, but it closes the possibility of better implementation of methods in derived classes. 
                      <CODE_SNIPPET>
                        class Base
                        {
                           virtual void f() final;
                        };

                        class Derived : Base
                        {
                           void f(); // ill-formed because the virtual method Base::f has been marked final
                        };
                      </CODE_SNIPPET>
                        
                        It can also be useful to prevent inheritance from classes (if a programmer tries to inherit from a class that is declared final by the 
                        author it is an indication that composition is more appropriate than inheritance in that case).
                      <CODE_SNIPPET>
                        class Base final { };
 
                        class Derived : Base { }; // ill-formed because the class Base has been marked final
                      </CODE_SNIPPET>
                    </p>
                </CPP11>
                <DEFINITION>
                    When a class inherits from a base class, it includes the
                    definitions of all the data and operations that the
                    base class defines.  In practice, inheritance is used in two
                    major ways in C++: implementation inheritance, in which
                    actual code is inherited by the derived class, and interface inheritance, 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 derived class is spread between the base and the derived class, it
                    can be more difficult to understand an implementation.  The
                    derived class cannot override functions that are not virtual, so
                    the derived class cannot change implementation.  The base class
                    may also define some data members, so that specifies physical
                    layout of the base class.
                </CONS>
                <DECISION>
                    <p>
                        All inheritance should be <code>public</code>.  If you want to
                        do private inheritance, you should be including an instance of
                        the base class as a member instead.
                    </p>
                    <p>
                        Do not overuse implementation inheritance.  Composition is
                        often more appropriate. 
                    </p>
                    <p>
                        State your intent when you want to override a virtual method by using the keyword <code>override</code>.
                    </p>
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Multiple Inheritance">
            <SUMMARY>
                Use multiple inheritance implementation only when at most one of
                the base classes has an implementation; all other base classes
                must be <A HREF="#Interfaces">pure interface</A> classes.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    Multiple inheritance allows a sub-class to have more than one
                    base class.  However this functionality can bring to the so-called <a href="http://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem">Diamond problem</a> unless base classes are pure interfaces.
                </DEFINITION>
                <!--PROS>
                 Multiple implementation inheritance may let you re-use even more code
                 than single inheritance (see <a HREF="#Inheritance">Inheritance</a>).
                 </PROS>
                 <CONS>
                 Only very rarely is multiple <em>implementation</em>
                 inheritance actually useful. When multiple implementation
                 inheritance seems like the solution, you can usually find a
                 different, more explicit, and cleaner solution.
                 </CONS-->
                <DECISION>
                    Multiple inheritance is allowed only when all superclasses, with the
                    possible exception of the first one, are <A HREF="#Interfaces">pure
                        interfaces</A>.
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Interfaces">
            <SUMMARY>
                If a class was designed as a pure interface, keep it as a pure interface.
            </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 (see <A HREF="#Destructors">Destructors</A>).
                        </li>
                        <li> It does not have data members.
                        </li>
                        <li> It does 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.
                        </li>
                    </ul>
                </DEFINITION>
                <DECISION>
                    When writing a pure interface, apply the <a href="#Interface_Names">corresponding naming rule</a> and
                    make sure there is no implementation in it.
                    Make sure not to add implementation to an existing pure interface.
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Operator Overloading">
            <SUMMARY>
                When overloading operators keep the same semantics.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    Operator overloading is a specific case of function overloading in which some or all operators like +, = or ==
                    have different behaviors depending on the types of their arguments.
                    It can easily be emulated using function calls.
                    <p>For example:
                        <code>
                            a &lt;&lt; 1;
                        </code>
                        shifts the bits of the variable left by one bit if a is an integer, but if a is an output stream instead this will write "1" to it.
                    </p>
                </DEFINITION>
                <DECISION>
                    <p>
                        The semantics of the operator overloading should be kept the same.
                        Because operator overloading allows the programmer to change
                        the usual semantics of an operator, it should be used with care.
                    </p>
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Access Control Keywords">
            <SUMMARY>
                The <code>public</code>, <code>protected</code> and <code>private</code> keywords must be used explicitly
                in the class declaration in order to make
                code more readable. It is recommended to list the public data member and methods first
                since they define the global interface and are most important for the user/reader.
            </SUMMARY>
            <BODY>
            <p>Don't do this:</p>
            <BAD_CODE_SNIPPET>
                class Momentum {
                   double mX;  // w/o access control keyword implicitly private
                   double mY;
                   double mZ;

                protected:
                   bool containsInvalidNumbers() const;

                public:             // should be listed first
                   double px() const;
                   double py() const;
                   double pz() const;
                   double pT() const;
                };
           </BAD_CODE_SNIPPET>
            <p>Do this:</p>
            <CODE_SNIPPET>
                class Momentum {
                public:
                   double px() const;
                   double py() const;
                   double pz() const;
                   double pT() const;
                    
                protected:
                    bool containsInvalidNumbers() const;
                     
                private:
                   double mX;
                   double mY;
                   double mZ;
                };
            </CODE_SNIPPET>
            </BODY>
            
        </STYLEPOINT>

        <STYLEPOINT title="Access Control">
            <SUMMARY>
                Hide internals. Avoid returning handles to internal data managed
                by your class.
            </SUMMARY>
            
            <BODY>
                <p>
                    Information hiding protects the code from uncontrollable modifying
                    state of your object by clients and it also help to minimize dependencies
                    between calling and called codes.
                </p>
                <p>
                    A class consisting mostly of gets/sets is probably poorly designed.
                    Consider providing an abstraction or changing it in <code>struct</code>.
                </p>
                <DECISION>
                    Make data members <code>private</code>, except in <code>structs</code>.
                    If there is no better way how to hide the class internals,
                    provide the access through protected or public accessor and,
                    if really needed, modifier functions.
                </DECISION>
                
                <p>
                    See also <a HREF="#Inheritance">Inheritance</a>,
                    <a HREF="#Structs_vs._Classes">Structs vs. Classes</a> and
                    <a HREF="#Function_Names">Function Names</a>.
                </p>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Friend Declaration">
            <SUMMARY>
                The use of friend declarations should be avoided where possible.
            </SUMMARY>
            
            <BODY>
                <DEFINITION>
                    Friends are a mechanism to override data hiding. Friends of a class have access to its private data.
                    Friend is a `limited export' mechanism.
                </DEFINITION>
                
                <CONS>
                    Friends have three problems:
                    <ul>
                    <li>They can change the internal state of objects from outside the definition of the class.</li>
                    <li>They introduce extra coupling between components, and therefore should be used sparingly.</li>
                    <li>They have access to everything, rather than being restricted to the members of interest to them.</li>
                    </ul>
                </CONS>
                <DECISION>
                    To guarantee the encapsulation of a base class is
                    always preferable to use protected data over friends or public data and then use inheritance.
                </DECISION>
            </BODY>
        </STYLEPOINT>

    </CATEGORY>
    
    <CATEGORY title="ROOT Related Issues">
        
        <STYLEPOINT title="ROOT Types">
            <SUMMARY>
            Use fundamental types provided by the C++ language over ROOT types, except in persistent
            classes that are subject to schema evolution.
            </SUMMARY>
            
            <BODY>
              <DEFINITION>
                <p>C++ provides a large set of fundamental types. Among them are <em>integral types</em> such as
                    Boolean, character, and integer types. Integral and floating-point types are collectively called
                    <em>arithmetic types</em>. Integral and floating point types are available in a variety of sizes.
                    These C++ fundamental types together with pointers and arrays present the machine-level notion
                    to the programmer in a reasonable implementation-independent manner.
                </p>
                <p>
                    ROOT defines a large set of portable and unportable types such as <CODE>Int_t</CODE>,
                <CODE>Float_t</CODE>, <CODE>Double_t</CODE>, and many more. Some, such as <code>Double32_t</code>
                and <code>Float16_t</code> have even different size in memory and when written.</p>
               </DEFINITION>
              
              <SUBSECTION title="Discussion:">
                <p>
                 There is a priori no reason to use ROOT types unless where absolutely needed (see below). Use of builtin C++
                 data types makes the code in fact more portable, readable, and often faster (see discussion under
                 <a href="#Integer_Types">"Extended integer types"</a>).
                 If fixed size is absolutely required the introduction of extended integer types of
                 fixed size and guaranteed size types in C++11 makes ROOT types redundant.
                </p>
                
                <p>
                    The use of ROOT types that have a different storage size in memory and when stored are inherently dangerous. Code
                    that uses for example <code>Double32_t</code>, will give different results dependent on if the variable was earlier
                    written to and from storage or if its value was assigned previously in memory.
                </p>

              </SUBSECTION>
 
              <SUBSECTION title="Exception:">
                <p>
                The only exceptions are data member in “persistent” classes in STAR that are under schema evolution.
                Here ROOT types need to be used to define the data members.
                The only persistent classes are those in StEvent and StMuDst. Any other class (e.g. makers, analysis code)
                should not use ROOT types.
                </p>
              </SUBSECTION>
 
              <DECISION>
                <p>
                  Do not use ROOT definitions of fundamental data types but use the available C++ data types.
                  Use <code>int</code> instead <code>Int_t</code>, <code>float</code> instead of <code>Float_t</code>,
                  <code>double</code> instead of <code>Double_t</code>, etc.
                </p>
                <p>
                   ROOT types of mixed memory and storage representation such as  <code>Double32_t</code> and <code>Float16_t</code> shall not be used in STAR without any exceptions.
                </p>
                </DECISION>
            </BODY>
        </STYLEPOINT>
      
      <STYLEPOINT title="ROOT Mathematical Function">
          <SUMMARY>
              Prefer the use of mathematical function available in the C++ standard (<code>&lt;cmath&gt;</code>) over those
              provided by ROOT.
          </SUMMARY>
          
          <BODY>
            <DEFINITION>
            <p>
                  ROOT provides a rich set of special mathematical functions often adapted from the old CERNLIB or,
                  more recently, wrapped GSL functions.  They are heavily used in STAR code. However, ROOT
                  also provides a set of basic mathematical functions that are already defined in <code>&lt;cmath&gt;</code>.
                  Examples are <code>TMath::Sqrt()</code>, <code>TMath::Log()</code>, <code>TMath::Sin()</code>, and many more.</p>
                  
                  <p>
                      There is no rational reason to use these ROOT functions when the same functionality is available in the standard
                  and defined in <code>&lt;cmath&gt;</code>. In most cases they are implemented by calling the built-in functions anyway
                  and their use reduces readability and portability.</p>
    
              </DEFINITION>
               <DECISION>
                   The use of ROOT mathematical function already available in <code>&lt;cmath&gt;</code> is strongly discouraged.
                    Use <code>sqrt()</code> instead of <code>TMath::Sqrt()</code>, use <code>log()</code> instead
                   of <code>TMath::Log()</code>, use <code>sin()</code> instead of <code>TMath::Sin()</code>, etc.
               </DECISION>
          </BODY>
      </STYLEPOINT>


    </CATEGORY>

    <CATEGORY title="Others">
        
            <STYLEPOINT title="Attributes" cpp11="yes">
                <SUMMARY>
                    "Attributes" is a new standard syntax aimed at providing some order in the mess of facilities for adding
                    optional and/or vendor specific information (GNU, IBM, …) into source code. The use of attributes is
                    discouraged in STAR.
                </SUMMARY>
                <BODY>
                <DEFINITION>
                    <p>Vendors use a multitude of methods to add  specific information into source code, mostly through preprocessor/macro statements such as
                    <code>__attribute__</code>, <code>__declspec</code>, and <code>#pragma</code>.
                    Attributes were added to C++ in order to unify and streamline this procedure.
                    As such their use for the common (STAR) programmer is limited. An attribute can be used almost everywhere in the C++ program,
                    and can be applied to almost everything: to types, to variables, to functions, to names, to code blocks, and to entire translation units,
                    although each particular attribute is only valid where it is permitted by the implementation.</p>
                
                    <p>An attribute is placed within double square brackets. There are few attributes defined yet: <code>[[noreturn]]</code>,
                        <code>[[carries_dependency]]</code>, <code>[[deprecated]]</code>(C++14), and <code>[[deprecated("reason")]]</code>(C++14).
                        Future attributes are in discussion to support MP.
                    </p>
                    Example:
                    <CODE_SNIPPET>
                        void boom [[ noreturn ]] ()	// boom() will never return
                        {
                           throw "error";
                        }
                    </CODE_SNIPPET>

                </DEFINITION>
                <DECISION>
                    The use  of attributes is discouraged in STAR. There is a reasonable fear that attributes will be misused.
                    The recommendation is to use attributes to only control things that do not affect the meaning of a program
                    but might help detect errors (e.g. [[noreturn]]) or help optimizers (e.g. [[carries_dependency]]).
                </DECISION>
                </BODY>
            </STYLEPOINT>
                

        <STYLEPOINT title="Strong Enums" cpp11="yes">
            <SUMMARY>
                Use strong enums instead of weak enums.
            </SUMMARY>
            
            <BODY>
                <p>
                    C++11 introduces strongly typed enums. They are what the name suggests. Enums with a type:
                    <CODE_SNIPPET>
                        enum class strongEnum {
                           one, two, three, four
                        };
                    </CODE_SNIPPET>
                    So the syntax stays similar and the class keyword is added. Additional, the underlying type can be specified.
                    If not defined it defaults to int or, if e.g. large values are defined, system default.
                    Strong enums solve the long standing problem with enums and scope.
                    The strong type is also an advantage. In addition strong enums allow forward declaration and a definite size.
                    Example:
                    <CODE_SNIPPET>
                        enum class  strongEnum : int{first, second};
                    </CODE_SNIPPET>
                    The advantage of strong enums is that they are strongly typed and have a scope. With weak enums the problem was e.g.
                    Example:
                    <BAD_CODE_SNIPPET>
                        enum weakEnum_color{red, green,blue};
                        //error: redefinition of enumerator red and green
                        enum weakEnum_trafficLight{red, green, yellow};
                        
                    </BAD_CODE_SNIPPET>
                    But this works:
                    
                    <CODE_SNIPPET>
                        enum class strongEnum_color{red, green,blue};
                        enum class strong_trafficLight{red, green, yellow};
                        strong_trafficLight trafficLight=strong_trafficLight::red;
                    </CODE_SNIPPET>
                    This does not work, wrong type
                    <BAD_CODE_SNIPPET>
                        strong_trafficLight trafficLight=strongEnum_color::red;
                    </BAD_CODE_SNIPPET>
                    Strong enums do not convert to int by default anymore (even if the underlying type is int), so you cannot write
                    <BAD_CODE_SNIPPET>
                        int c= strongEnum_color::red;
                    </BAD_CODE_SNIPPET>
                    But you can use casts e.g. if you want to use <code>cout</code>:
                    <CODE_SNIPPET>
                        int c= static_cast &lt; int &gt; (strongEnum_color::red);
                    </CODE_SNIPPET>
                </p>
                <p>
                  Note that while we encourage the use of strong enums be aware that currently ROOT I/O us not supporting to store these values. 
                  However, there’s no case we are aware of where enums are stored in the first place.
                </p>
            </BODY>
        </STYLEPOINT>
        
        
        <STYLEPOINT title="Lambda Expressions" cpp11="yes">
            <SUMMARY>
                Lambda functions are a powerful addition. They can be very useful in particular when iterating over containers. They should not be used for regular functions as there might be a performance penalty when they are called often.
                Capture by reference can lead to side-effects. Therefore capture by reference is discouraged.
                
            </SUMMARY>
            <BODY>
                <p>
                    C++11 added Lambda functions (closures). This concept usually known from functional programming allows the creation of anonymous inline functions.
                    Lambda functions can access variables of the enclosing functions (variable capture) either by value or by reference.
                    Lambdas e.g. valuable with the std libraries iteration functions:
                </p>
                <p>
                    Examples:
                    <CODE_SNIPPET>
                        std::vector&lt;int&gt; v;
                        v.push_back(1);
                        v.push_back(2);
                        v.push_back(3);
                        
                        //  iterate over vector and print out each element
                        std::for_each(std::begin(v),std::end(v),[](int n) { std::cout &lt;&lt; n &lt;&lt; std::endl; } );
                        
                        //  declare is_odd to be lambda function that returns true if
                        //  the argument is odd. Note the return syntax
                        //  Note that the return type can be omitted. It is then
                        //  determined as if auto is applied to the statement after return;
                        
                        auto is_odd=[](int n)-&gt;bool{return n%2==true;};
                        auto pos=std::find_if(std::begin(v),std::end(v), is_odd);

                        //  the below snippet returns 1 (the first position with an odd number
                        if(pos!=std::end(v))
                           std::cout &lt;&lt; *pos &lt;&lt; std::endl;
                    </CODE_SNIPPET>
                </p>
                A lambda function is of type <code>std::function</code>, therefore instead of <code>auto</code>, the above return type for <code>is_odd</code>_ could be written as <code>std::function&lt;bool(int)&gt; is_odd; </code>
                
                <p>
                    
                    A powerful feature of lambda functions is that variables of the surrounding function can be captured. This is what the [] part of the function is for.
                    <ul>
                        <li>	<code>[]</code> No capture </li>
                        <li>	<code>[=]</code> capture by copy </li>
                        <li>	<code>[&amp;]</code> capture by reference </li>
                        <li>	<code>[a,b]</code> capture only <code>a,b </code>by copy </li>
                        <li>	<code>[&amp;a,b]</code> capture <code>a</code> by reference, <code>b</code> by copy </li>
                    </ul>
                    
                    If the function is also modifying the variables that are captured by copy or wants to access the non-const members of a captured object, the lambda function has to be declared as ‘mutable’. Note that this does not modify the captured variable in the surrounding function
                </p>
                <p>
                    Example (Gives output <code>“a is now 5”</code>):
                    <CODE_SNIPPET>
                        int a=5;
                        auto testCopy=[a]()mutable {a=7;};
                        testCopy();
                        cout &lt;&lt; "a is now " &lt;&lt; a &lt;&lt; endl;
                    </CODE_SNIPPET>
                </p>
                <p>
                    
                    Example (Gives output <code>“a is now 7”</code>):
                    <CODE_SNIPPET>
                        int a=5;
                        auto testCopy=[&amp;a](){a=7;};
                        testCopy();
                        cout &lt;&lt; "a is now " &lt;&lt; a &lt;&lt; endl;
                    </CODE_SNIPPET>
                </p>
                <p>
                    Example does not compile (mutable missing)
                    <BAD_CODE_SNIPPET>
                        int a=5;
                        auto testCopy=[a](){a=7;};
                        testCopy();
                        cout "a is now " &lt;&lt; a &lt;&lt; endl;
                    </BAD_CODE_SNIPPET>
                    Obviously, capturing variables by reference can lead to side-effects.
                    Another danger in capturing variables by reference is that the reference might not be valid anymore when the lambda function is called:
                </p>
                <p>
                    Example:
                    <CODE_SNIPPET>
                        function&lt;int (float)&gt; retLambda(int a, int&amp; b)
                        {
                           int c=5;
                           // if this is &amp; (i.e. pass by reference, it doesn't work... (a,b, are nonsense)
                           return [&amp;] (float d) -&gt;int {cout &lt;&lt; "lambda param: " &lt;&lt; d &lt;&lt; ", a: " &lt;&lt; a &lt;&lt; " b : " &lt;&lt; b &lt;&lt; " c: " &lt;&lt; c &lt;&lt; endl;
                           b=7;
                           cout &lt;&lt; " lambda b is now " &lt;&lt; b &lt;&lt; endl;
                           return a+b+c;};
                        }

                        void testVarByReference()
                        {
                           int a=1;
                           int b=2;
                           int c=3.0;
                           auto f=retLambda(a,b);
                           cout &lt;&lt; " lambda returns " &lt;&lt;  f(c) &lt;&lt; endl;
                           cout &lt;&lt; " b is now " &lt;&lt; b &lt;&lt; endl;
                        }
                    </CODE_SNIPPET>
                </p>
                <p>
                    In the above example there are several things that are noteworthy:
                    <ul>
                        <li>	The function that returns a lambda function has the return type function <code>&lt;int (float)&gt; </code></li>
                        <li>	All variables are captured by reference. However when the lambda function <code>f</code> is called in <code>testVarByReference</code>, all variables that where on the stack of the function that generated the lambda function (<code>retLambda</code>) are invalid. That means that <code>c</code> and <code>a</code> are invalid. </li>
                        <li>	The variable that was given by reference, <code>b</code>, is still valid. In fact it is modified in the lambda function, so that it has the value <code>7</code> after the lambda function is called. </li>
                    </ul>
                                   </p>
                <DECISION>
                    Lambda functions is a new C++ feature worth getting familiar with.
                    They can be very useful in particular when iterating over containers.
                    They should not be used for regular functions and capture by reference
                    is discouraged.
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        
        <STYLEPOINT title="decltype" cpp11="yes">
            <SUMMARY>
                Do not use <code>decltype</code> if you can use <code>auto</code>. <code>decltype</code> is useful for templates, since there is no other way to declare the return type of a function if the return type depends on the parameter.
            </SUMMARY>
            <BODY>
                <p>
                    <code>decltype</code> can be used to get the type of a variable. Its simple use is very similar to the <code>auto</code> statement
                    
                </p>
                <p>
                    Example:
                </p>
                <CODE_SNIPPET>
                    
                    int x=7;
                    decltype(x) y=x;
                    //same thing
                    auto y2=x;
                    
                </CODE_SNIPPET>
                <p>
                    It can be used for lambda functions, but here <code>auto</code> works as well:
                </p>
                <p>
                    Example:
                </p>
                
                <CODE_SNIPPET>
                    auto f = [] (int a, int b) -&gt; int { return a*b;};
                    
                    decltype(f) f2=f;
                    //works as well, so use of decltype not necessary
                    auto f3=f;
                    
                </CODE_SNIPPET>
                <p>
                    The most common use case for <code>decltype</code> is to declare a return type that is part of a template parameter.
                </p>
                <p>
                    Example:
                </p>
                <CODE_SNIPPET>
                    class A
                    {
                    public:
                       int makeObject() const {return 8;};
                       A() {};
                    };

                    template &lt;typename Builder&gt;
                    auto makeAndProcessObject(const Builder&amp; builder) -&gt; decltype( builder.makeObject() )
                    {
                       auto val = builder.makeObject();
                       // do stuff with val
                       return val;
                    }
                    
                    
                </CODE_SNIPPET>
                </BODY>
            </STYLEPOINT>


            <STYLEPOINT title="Exception Handling">
            <SUMMARY>
                Do not use C++ exception handling in STAR code unless absolutely necessary.
            </SUMMARY>
            <BODY>
                <p>
                    Exception handling is a powerful tool when used <em>consistently</em>. The beginning of the STAR framework
                    goes back to a time when exception handling was not well established and hence was not used. Instead STAR
                    implemented an alternative described in the <a href="formatguide.xml">STAR C++ Naming &amp; Formatting Guidelines</a>
                    under "Handling Error Conditions in STAR Framework". Due to legacy reasons it is not advisable to introduce
                    C++ exceptions now. Attempts to introduce it in the past caused substantial problems.
                    STAR code is/was in general not written with exception safety in mind.
                </p>
                <p>
                It is of course OK to use it in your private code, as long as you make sure that you use it consistently.
                Be aware of the pros and cons:
                </p>
                <PROS>
                 <ul>
                    <li>Exceptions separate error-handling code from the normal program flow and thus make the code more readable, robust, and extensible.</li>
                    <li>Throwing an exception is the only clean way to report an error from a constructor.</li>
                    <li>Exceptions are hard to ignore, unlike error codes.</li>
                    <li>Exceptions are easily propagated from deeply nested functions.</li>
                    <li>Exceptions can be, and often are, user defined types that carry much more information than an error code.</li>
                    <li>Exception objects are matched to the handlers by using the type system.</li>
                    </ul>
                </PROS>
               <CONS>
                   <ul>
                   <li>Exceptions break code structure by creating multiple invisible exit points that make code hard to read and inspect.</li>
                   <li>Exceptions easily lead to resource leaks.</li>
                   <li>Learning to write Exception safe code is hard.</li>
                   <li>Exceptions are hard to introduce to legacy code.</li>
                   <li>Exceptions are easily abused for performing tasks that belong to normal program flow.</li>
                   </ul>
                </CONS>
               <SUBSECTION title="Should you chose to use them in your own code:">
                <p>
                    Note that exception classes typically derive from <code>std::exception</code> (or one of its subclasses like <code>std::runtime_error</code>).<br />
                    Exceptions should be scoped inside the class that throws them. By default, catch exceptions by reference.<br />
                    Example:<br />
                    <CODE_SNIPPET>
                        int computePedestals()
                        {
                           ...
                           if (somethingWrong) {
                               throw BadComputation();
                           }
                           ...
                        }

                        try {
                           computePedestals();
                        }
                        catch (BadComputation&amp; e) {  // catch exception by reference
                           // code that handles error
                           ...
                        }
                    </CODE_SNIPPET>
                  </p>
                </SUBSECTION>
                <SUBSECTION title="If you chose to use exceptions:">
                  <ul>
                    <li>Don not hide exception by using a catch followed by an empty code block.</li>
                    <li>Don not EVER use exception to indicate the absence of a resource.</li>
                    <li>Similarly, don't use exception as a mean to return special information from a method.</li>
                    <li>Use exception ONLY for errors that should not be ignored.</li>
                    <li>Do not clear the stack trace by re-throwing an exception i.e.:
                        <BAD_CODE_SNIPPET>
                        catch (Exception ex)
                        {
                           // some code here
                           throw ex;
                        }
                        </BAD_CODE_SNIPPET>
                       should not be used as "throw ex" will throw a new exception and clear the stack trace (bad for code developers). Instead, use:
                       <CODE_SNIPPET>
                        catch (Exception ex)
                        {
                           // some code here
                           throw;
                        }
                       </CODE_SNIPPET>
                       which will not clear the stack.
                    </li>
                  </ul>
                </SUBSECTION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Use of const">
            <SUMMARY>
                Declare objects that are logically constant as <code>const</code>.
                Design const-correct interfaces.
                Consider <a href="#Use_of_constexpr"><code>constexpr</code></a> for some uses of const.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    <CPP11>
                        <p>
                            The Standard Library […] in simple words says that it expects operations on const objects to be thread-safe.
                            This means that the Standard Library won't introduce a data race as long as operations on const objects of your own types either
                            <ul>
                                <li>Consist entirely of reads –that is, there are no writes–; or</li>
                                <li>Internally synchronizes writes.</li>
                            </ul>
                            [Source: <a href="http://stackoverflow.com/questions/14127379/does-const-mean-thread-safe-in-c11">Stack Overflow</a>]
                        </p>
                        
                        <p>
                            This is a great example of how C++11 is a simpler language: we can stop the Cold War-era waffling about subtleties about what 20th-century C++ const means, and proudly declare modern C++ const has the simple and natural and “obvious” meaning that most people expected all along anyway.
                        </p>
                        <p>
                            […] Bjarne Stroustrup writes: “I do point out that const means immutable and absence of race conditions in the last Tour chapter. […]”
                        </p>
                        [Source: <a href="http://isocpp.org/blog/2012/12/you-dont-know-const-and-mutable-herb-sutter">isocpp.org</a>]
                    </CPP11>
                    Variables and parameters can be declared as <code>const</code> to indicate that the variables are logically immutable.
                    (Because of <code>const_cast</code> and <code>mutable</code> member variables, and global variables, <code>const</code> is no hard guarantee for immutability.)
                    Member functions can be declared <code>const</code> to allow calls with <code>const</code> <code>this</code> pointer.
                    Note that overloading member functions on <code>const</code> is possible.
                </DEFINITION>
                <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>
                    
                    <p> Use <code>const</code>:
                        <ul>
                            <li>
                                for an argument, if the function does not modify it when passed by reference or by pointer.
                            </li>
                            <li>For accessors.</li>
                            <li>
                                For methods, if they:
                                <ul>
                                    <li>do not modify any non-local data;</li>
                                    <li>can be safely (no data race) called from multiple threads;</li>
                                    <li>do not call any non-<code>const</code> methods;</li>
                                    <li>do not return a non-<code>const</code> pointer or non-<code>const</code> reference to a data member.</li>
                                </ul>
                            </li>
                            <li>
                                For data members, whenever they do not need to be modified after construction.
                            </li>
                        </ul>
                    </p>
                </DECISION>
                <EXTRA>
                    <p>
                        <code>mutable</code> can be used to make objects that are already thread-safe (such as <code>std::mutex</code>) mutable in <code>const</code> methods.
                        Thus, it is possible to make <code>const</code> methods thread-safe, through internal synchronization.
                    </p>
                </EXTRA>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Use of constexpr" cpp11="yes">
            <SUMMARY>
                In C++11, use <code>constexpr</code> to define true constants or to ensure constant initialization. When used with functions you should also declare 
                them <code>const</code> for forward consistency reasons (see notes below).
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    One of the improvements in C++11, generalized constant expressions, allows programs to take
                    advantage of compile-time computation. It is a feature that, if used correctly, can speed up programs.
                    The basic idea of constant expressions is to allow certain computations to take place at compile
                    time—literally while your code compiles—rather than when the program itself is run.

                    <CODE_SNIPPET>
                        constexpr int multiply(int x, int y) const
                        {
                           return x*y;
                        }
                        
                        constexpr int factorial(int n) const
                        {
                           return n &lt;= 1 ? 1 : (n * factorial(n-1));
                        }
                    </CODE_SNIPPET>
                    Then the compiler will evaluate the following statements at compile time instead at run time:
                    
                    <CODE_SNIPPET>
                        const int val multiply(10,10);
                        const int n5 factorial(5);
                    </CODE_SNIPPET>
                    <p>
                    Another benefit of <code>constexpr</code>, beyond the performance of compile time computation, is that it
                    allows functions to be used in all sorts of situations that previously would have called for macros.
                    For example, let's say you want to have a function that computes the the size of an array based on
                    some multiplier. If you had wanted to do this in C++ without a <code>constexpr</code>, you'd have needed to create
                    a macro since you can't use the result of a function call to declare an array. But with <code>constexpr</code>,
                    you can now use a call to a <code>constexpr</code> function inside an array declaration.</p>
                    Example:
                    <CODE_SNIPPET>
                        constexpr int defaultArraySize(int multiplier)
                        {
                           return 10*multiplier;
                        }
                    </CODE_SNIPPET>
                    and in the program it is now possible to use:
                    <CODE_SNIPPET>
                        int array[defaultArraySize(3)];
                    </CODE_SNIPPET>
                    
                    <p>Note that:
                       <ul>
                         <li>A <code>constexpr</code> specifier used in a function declaration implies inline.</li>
                         <li>If you declare a class member function to be <code>constexpr</code> you should declare it <code>const</code> as well.
                             In C++11, constexpr functions are const. C++14 had to change that. Thus <em>always</em> specify <code>constexpr f() const</code>. 
                             This will guarantee our code remains unchanged both in spelling and meaning if we move to C++14 in the future.
                             It will also gets rid of the warning "the meaning of this changes in C++14!"`
                         </li>
                         <li>If you declare a variable as <code>constexpr</code>, that in turn marks the variable as <code>const</code>. However, it doesn't work the 
                             other way, a <code>const</code> variable is not a <code>constexpr</code>.</li>
                       </ul>
                     </p>
                     <p>
                       You can make any object a <code>constexpr</code>. In this case the constructor must be
                       declared a <code>constexpr</code> as well as the method to be used.
                       There are also some limitations:
                       <ul>
                         <li>It must consist of single return statement (with a few exceptions)</li>
                         <li>It can call only other <code>constexpr</code> functions</li>
                         <li>It can reference only <code>constexpr</code> global variables</li>
                       </ul>
                    </p>
                    <p>
                        Some variables can be declared <code>constexpr</code>
                        to indicate the variables are true constants,
                        i.e. fixed at compilation/link time.
                        Some functions and constructors can be declared <code>constexpr</code>
                        which enables them to be used
                        in defining a <code>constexpr</code> variable.
                    </p>
                    
                </DEFINITION>
                <PROS>
                    Use of <code>constexpr</code> enables
                    definition of constants with floating-point expressions
                    rather than just literals;
                    definition of constants of user-defined types; and
                    definition of constants with function calls.
               </PROS>
                <CONS>
                    Prematurely marking something as <code>constexpr</code>
                    may cause migration problems if later on it has to be downgraded.
                    
                    Current restrictions on what is allowed
                    in <code>constexpr</code> functions and constructors
                    may invite obscure workarounds in these definitions.
                    
                </CONS>
                <DECISION>
                    <p>
                        <code>constexpr</code> definitions enable a more robust
                        specification of the constant parts of an interface.
                        Use <code>constexpr</code> to specify true constants
                        and the functions that support their definitions.
                        Avoid complexifying function definitions to enable
                        their use with <code>constexpr</code>.
                        Do not use <code>constexpr</code> to force inlining.
                    </p>
                    
                    
                </DECISION>
                <EXTRA>
                    While <code>constexpr</code> variables are constant expressions, they can still have an address.
                    Thus, using a <code>constexpr</code> variable as argument for a const-ref function parameter requires the <code>constexpr</code> variable to have a symbol.
                    Consider the following header file:
                    <CODE_SNIPPET>
                        constexpr int GlobalScopeValue = 0;
                        
                        namespace Namespace {
                        constexpr int ScopeValue = 1;
                        }
                        
                        struct Struct {
                           static constexpr int ScopeValue = 1;
                        };
                        
                        template&lt;typename T&gt; struct TemplateStruct {
                           static constexpr int ScopeValue = 1;
                        };
                        
                        void function(const int &amp;value);
                    </CODE_SNIPPET>
                    And the following test code:
                    <CODE_SNIPPET>
                        function(GlobalScopeValue);      // fine
                        function(Namespace::ScopeValue); // fine
                        function(Struct::ScopeValue);    // link error
                        function(TemplateStruct&lt;int&gt;::ScopeValue); // link error
                    </CODE_SNIPPET>
                    
                    To provide the missing symbols you have to add
                    <CODE_SNIPPET>
                        template&lt;typename T&gt; constexpr int TemplateStruct&lt;T&gt;::ScopeValue;
                    </CODE_SNIPPET>
                    to the header file and
                    <CODE_SNIPPET>
                        constexpr int Struct::ScopeValue;
                    </CODE_SNIPPET>
                    to one <code>.cxx</code> file.
                </EXTRA>
            </BODY>
        </STYLEPOINT>
  
        <STYLEPOINT title="Suffix Return Type Syntax" cpp11="yes">
            <SUMMARY>
                C++11 new suffix return value syntax (or extended function declaration syntax) represents another use for <code>auto</code>.
                It is useful mostly in templates and in methods where the return type is the class itself. The new return syntax,
                however, is not as easy to read as the standard method and should only be used where necessary. It should not be
                regarded as an alternative way of defining a simple function.
            </SUMMARY>
            <BODY>
                <p>In all prior versions of C and C++, the return value of a function absolutely had to go before the function:</p>
                
                <CODE_SNIPPET>
                    int multiply (int x, int y);
                </CODE_SNIPPET>
                        
                In C++11, you can now put the return value at the end of the function declaration, substituting <code>auto</code> for the name of the return type.
                
                <CODE_SNIPPET>
                    auto multiply (int x, int y) -&gt; int;
                 </CODE_SNIPPET>
                        
                <p>In the above example the use of the new syntax does not provide any advantage, in fact it makes it less readable.
                However, there are several cases were the new syntax is in fact the only way to make things work.</p>
                
                Consider:
                
                    <CODE_SNIPPET>
                    template&lt;class T, class U&gt;
                    ??? add(T x, U y)
                    {
                       return x+y;
                    }
                    </CODE_SNIPPET>
                        
                    What can we write as the return type? It's the type of “<code>x+y</code>", of course,
                    but how can we say that? First idea, use <code>decltype</code>:
                    
                    <BAD_CODE_SNIPPET>
                    template&lt;class T, class U&gt;
                    decltype(x+y) add(T x, U y) // scope problem!
                    {
                       return x+y;
                    }
                    </BAD_CODE_SNIPPET>
                            
                    That won't work because x and y are not in scope.
                    The solution is put the return type where it belongs, after the arguments:
                        
                        
                    <CODE_SNIPPET>
                    template&lt;class T, class U&gt;
                    auto add(T x, U y) -&gt; decltype(x+y)
                    {
                       return x+y;
                    }
                    </CODE_SNIPPET>
                                
                    We use the notation auto to mean "return type to be deduced or specified later."
                    The suffix syntax is not primarily about templates and type deduction, it is really about scope.

                <DECISION>
                    The use of the new return type syntax is very useful in templates and in methods where the return type
                    is the class itself. See also <code>decltype</code>. The new return syntax, however, is not as easy to read as the
                    standard method and should only be used where necessary and to simplify the code. It should not be
                    regarded as an alternative way of defining a simple function. Use the suffix syntax only if absolutely required.
                </DECISION>
            </BODY>
         </STYLEPOINT>
        
        <STYLEPOINT title="Smart Pointers" cpp11="yes">
            
            <SUMMARY>
              It is a modern C++ idiom to get rid of naked pointers whenever possible. However, it is currently difficult to devise an error free scheme where smart pointers
              can live in harmony with ROOT object ownership and management rules. Avoid using smart pointers in STAR code.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    <CPP11 title="Smart Pointers">
                        Smart pointers have existed long before C++11.
                        But since C++11 the standard library contains the classes <code>unique_ptr&lt;T&gt;</code>,
                        <code>shared_ptr&lt;T&gt;</code>, and <code>weak_ptr&lt;T&gt;</code>.
                        Also, the standard library provides <code>make_shared&lt;T&gt;</code> and starting with C++14 also <code>make_unique&lt;T&gt;</code>.
                    </CPP11>
                    Smart pointers are objects that act like pointers, but automate ownership.
                    There are two main semantics for ownership: unique and shared ownership.
                    <p>
                        Unique ownership ensures that there can be only one smart pointer to the object.
                        If that smart pointer goes out of scope it will free the pointer.
                    </p>
                    <p>
                        Shared ownership allows to have multiple pointers to an object without deciding who is the exclusive owner.
                        Thus the owners can be freed in any order and the pointer will stay valid until the last one is freed, in which case the pointer is also freed.
                        Note that <code>shared_ptr&lt;T&gt;</code> is thread-safe and thus enables sharing ownership over multiple threads.
                    </p>
                    <p>
                        Example:
                        <CODE_SNIPPET>
                          {
                             std::shared_ptr&lt;int&gt; first;
                             {
                                std::unique_ptr&lt;int&gt; second(new int);
                                auto third = std::make_shared&lt;int&gt;();
                                first = third;
                             }
                             // only second is freed automatically here
                          }
                          // first and third are automatically freed here
                        </CODE_SNIPPET>
                        When exiting the inner scope, only <code>second</code> is freed automatically, because the last
                        reference to it went out of scope. But even though  <code>third </code> went out of scope here,
                        no free occurred because <code>first</code> still has a reference.  Only when <code>first</code>
                        went out of scope and as it is the last reference, <code>third </code> is automatically freed.
                    </p>
                </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>
                  Smart pointers are not easy to work with in an environment where ROOT is used (another possible conflict is with STAR "WhiteBoard" of <code>StMaker</code>s).
                  <CODE_SNIPPET>
                    int main()
                    {
                       TFile f("out.root", "recreate");
                       f.cd();
                       std::unique_ptr&lt;TH1F&gt; h {new TH1F("h", "h", 100, -5, 5)};
                       h->FillRandom("gaus", 10000);
                       h->Write();
                       f.Close();

                       return 0;
                    }
                  </CODE_SNIPPET>

                  The histogram which is handled by a unique pointer is owned by the current <code>gDirectory</code>
                  pointing to the opened ROOT file. When the file is closed with <code>f.Close()</code> the histogram
                  object is destroyed by the internal ROOT memory management. This will prevent the unique pointer to
                  properly clean up its resources when it goes out of scope at the end of <code>main()</code>.
                </CONS>

                <DECISION>
                  For the cons mentioned above using smart pointers in STAR code is discouraged. If you decide to use them you should pay special attention 
                  to possible conflicts with ROOT object ownership scheme.
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Magic Numbers (Hard Coded Numbers)">
            <SUMMARY>
                <p>
                    Avoid magic numbers (hard coded numbers).
                </p>
            </SUMMARY>
            <BODY>
                <p>Avoid spelling literal constants like <code>42</code> or
                    <code>3.141592</code> in code.  Hard-coded numbers within the code reduce portability and make maintainability
                    harder. The use of symbolic names and expressions (declared ) is a valid solution. Make use of <code>const</code>
                    and <code>constexpr</code>. Names add information and introduce
                    a single point of maintenance.
                </p>
                <p>
                    Example of constants at namespace level:
                </p>
                <CODE_SNIPPET>
                    static constexpr double Millimeter  = 1.;
                    static constexpr double Centimeter  = 10.*Millimeter;
                </CODE_SNIPPET>
                <p>
                    Example of class-specific constants:
                </p>
                <CODE_SNIPPET>
                    // File Widget.h
                    class Widget {
                    private:
                        static const int sDefaultWidth;           // value provided in definition
                        static constexpr int DefaultHeight = 600; // value provided in declaration
                    };
                </CODE_SNIPPET>
                <CODE_SNIPPET>
                    // File Widget.cxx
                    const int Widget::sDefaultWidth = 800; // value provided in definition
                    constexpr int Widget::DefaultHeight;   // definition required only if reference/pointer to
                    // DefaultHeight is needed
                </CODE_SNIPPET>
                <SUBSECTION title="STAR Database">
                    <p>For values which are likely to change with time, a database approach
                    should be considered. Refer to the STAR database Web page area for more information.</p>
                 </SUBSECTION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Preprocessor Macros">
            <SUMMARY>
                Avoid macros. Use inline functions, constexpr functions, enums,
                constexpr variables, or templates instead if they can solve the
                problem.
            </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>
                    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> Define macros (via <code>#define</code>) right before you use them,
                        and undefine them  (via <code>#undef</code>) right after.
                    </li>
                    <li> Do not just undefine an existing macro (via <code>#undef</code>) 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>
                    <li> Follow the naming convention as described <a href="#Macro_Names">here</a>.
                    </li>
                </ul>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Write Short Functions">
            <SUMMARY>
                Prefer small and focused functions.
            </SUMMARY>
            <BODY>
                <p>
                    Long functions are hard to debug and makes readability difficult. Short functions allow code reuse.
                    If a function exceeds about 40 lines, think about whether it can be broken
                    up without harming the structure of the program.<br/>
                    Giving the function a name that describes what it does might help splitting it into smaller pieces.
                    Functions should represent logical grouping, therefore it should be easy to assign them meaningful names.<br/>
                    
                    Please note that nesting is not the same as splitting long functions into short ones.
                    In addition, it does not improve readability and ease of debug.
                </p>
            </BODY>
          </STYLEPOINT>

          <STYLEPOINT title="Inline Namespaces and Align Statements" cpp11="yes" nobutton="yes">
            <SUMMARY>
              Both, inline namespaces and align statements are new in C++11. Use cases are limited enough that no specific recommendations for their use are made.
            </SUMMARY>
          </STYLEPOINT>

        
        <!-- <STYLEPOINT title="Function Parameters (Matthias)">
         <SUMMARY>
         Function parameters should be by value or by const reference.
         Limit the number of parameters to two or at maximum three.
         </SUMMARY>
         <BODY>
         <DEFINITION>
         <p>
         Functions allow an arbitrary number of parameters with many different forms of parameter passing:
         <ul>
         <li>by value: <code>f(int)</code></li>
         <li>by reference: <code>f(int &amp;)</code></li>
         <li>by const reference: <code>f(const int &amp;)</code></li>
         <li>as pointer: <code>f(int *)</code></li>
         <li>as pointer to const: <code>f(const int *)</code></li>
         <li>as const pointer: <code>f(int *const)</code></li>
         <li>as const pointer to const: <code>f(const int *const)</code></li>
         <li>by rvalue reference: <code>f(int &amp;&amp;)</code></li>
         <li>... and more</li>
         </ul>
         Some of the above allow the function body to modify the value.
         Some of those will make the changes visible to the caller.
         </p>
         <p>
         By looking at a C/C++ function call it is impossible to know which arguments will/may be modified by the function without looking at the function signature.
         Even then, the signature may be misleading and the function does not change the values of the arguments, even though the signature allows it.
         </p>
         <p>
         In some designs function parameters are used to return results to the caller.
         This is often the case if a function returns more than one object, or must return an error code in addition to a value.
         </p>
         </DEFINITION>
         <DECISION>
         <p>
         Limit function argument usage to inputs.
         Then, the only two useful variants for parameter passing are by value and by const reference.
         Use const-reference when a copy of the object is expensive and not required.
         If a copy is required anyway, or if the parameter is a builtin type consider passing by value.
         </p>
         <p>
         Use return values for return values — not function parameters.
         You do not need to return error codes anyway because exceptions are used instead.
         If you still need to return multiple values use an appropriate structure or a <code>std::tuple</code>.
         </p>
         <p>
         By disallowing return values in function arguments, code becomes much easier to read since the flow of data is obvious.
         </p>
         <p>
         Use only few function parameters because this makes the function's signature easy to memorize and understand.
         Thus, it helps code readability and maintainability.
         </p>
         </DECISION>
         </BODY>
         </STYLEPOINT>
         
         <STYLEPOINT title="Function Parameters">
         <SUMMARY>
         Take parameters appropriately by value, (smart) pointer, or reference.
         The order : inputs, then outputs.
         </SUMMARY>
         <BODY>
         <p>
         Parameters to C/C++ functions are either input to the
         function, output from the function, or both. 
         </p>  
         <DECISION>
         <p> The guidelines for choosing how to take parameters:</p> 
         <p> For input parameters: 
         <ul>
         <li> Always const-qualify all pointers and references to input-only parameters. </li>
         <li> Prefer taking inputs of primitive types (eg. char. float) and value objects
         that are cheap to copy (eg. Point, complex &lt;float&gt;) by value. </li>
         <li> Prefer taking inputs for other user-defined types by reference to const. </li>
         <li> Consider pass-by-value instead of reference if the function requires a copy
         of its argument. </li>
         </ul>     
         </p>
         <p> For input or input/output parameters: 
         <ul>
         <li> Prefer passing by (smart) pointer if the argument is optional or if the 
         function stores a copy of the pointer or otherwise manipulates ownership
         of the argument. </li>
         <li> Prefer passing by reference  if the argument is required and the function
         won't store a pointer to it or otherwise affects its ownership. </li>   
         </ul>
         </p>
         <p> Don't use C-style varargs.
         </p>
         </DECISION>
         </BODY>
         </STYLEPOINT>-->
        
        
        <STYLEPOINT title="Run-Time Type Information (RTTI)">
            <SUMMARY>
              Use RTTI with caution. If you find yourself overusing <code>dynamic_cast</code> consider reviewing the design of your code and classes.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    RTTI allows a programmer to query the C++ class of an
                    object at run time.  This is done by use of <code>typeid</code> or
                    <code>dynamic_cast</code>.
                </DEFINITION>
                <CONS>
                    <p>
                        Querying the type of an object at run-time frequently means a
                        design problem and is often an indication that
                        the design of your class hierarchy is flawed.
                    </p>
                    <p>
                        Undisciplined use of RTTI makes code hard to maintain.  It can
                        lead to type-based decision trees or switch statements scattered
                        throughout the code, all of which must be examined when making
                        further changes.
                    </p>
                    <p>
                        Decision trees based on type are a strong indication that your
                        code is on the wrong track.
                        <BAD_CODE_SNIPPET>
                            if (typeid(*data) == typeid(Data1)) {
                               ...
                            } else if (typeid(*data) == typeid(Data2)) {
                               ...
                            } else if (typeid(*data) == typeid(Data3)) {
                               ...
                            }
                        </BAD_CODE_SNIPPET>
                        Code such as this usually breaks when additional subclasses are
                        added to the class hierarchy.  Moreover, when properties of a subclass
                        change, it is difficult to find and modify all the affected code segments.
                    </p>
                </CONS>
                <PROS>
                    <p>
                        The standard alternatives to RTTI (described below) require
                        modification or redesign of the class hierarchy in question.
                        Sometimes such modifications are infeasible or undesirable,
                        particularly in widely-used or mature code.
                    </p>
                    <p>
                        RTTI can be useful in some unit tests. For example, it is useful in
                        tests of factory classes where the test has to verify that a
                        newly created object has the expected dynamic type.  It is also
                        useful in managing the relationship between objects and their mocks.
                    </p>
                    <CODE_SNIPPET>
                        // Example of a unit test
                        Geo::Factory geoFactory;
                        Geo::Object* circle = geoFactory.CreateCircle();

                        if ( !dynamic_cast&lt;Geo::Circle&gt;(circle) ) {
                           std::cerr &lt;&lt; "Unit test failed."  &lt;&lt; std::endl;
                        }  
                    </CODE_SNIPPET>
                </PROS>
                <DECISION>
                    <p>
                        RTTI has legitimate uses but is prone to abuse, so you must
                        be careful when using it.  You may use it freely
                        in unit tests, but avoid it when possible in other code.
                        In particular, think twice before using RTTI in new code.
                        If you find yourself needing to write code that behaves differently
                        based on the class of an object, consider one of the following
                        alternatives to querying the type:
                        <ul>
                            <li>
                                Virtual methods are the preferred way of executing different
                                code paths depending on a specific subclass type.  This puts
                                the work within the object itself.
                            </li>
                            <li>
                                If the work belongs outside the object and instead in some
                                processing code, consider a double-dispatch solution, such
                                as the Visitor design pattern.  This allows a facility
                                outside the object itself to determine the type of class
                                using the built-in type system.
                            </li>
                        </ul>
                    </p>
                    <p>
                        When the logic of a program guarantees that a given instance
                        of a base class is in fact an instance of a particular derived class,
                        then use of a <code>dynamic_cast</code> or <code>static_cast</code> 
                        as an alternative may be also justified in such situations.
                    </p>
                </DECISION>
                <EXTRA>
                    <p>
                        An example of code based on <code>dynamic_cast</code>:
                    </p>
                    <BAD_CODE_SNIPPET>
                        void foo(Bar* bar) {
                           // Some code where x, y, z are defined
                           // ...
                           if (Data1 data1 = dynamic_cast&lt;Data1*&gt;(bar)) {
                              doSomething(data1, x, y);
                           }
                           else if (Data2 data2 = dynamic_cast&lt;Data2*&gt;(bar)) {
                              doSomething(data2, z)
                           }
                        }
                    </BAD_CODE_SNIPPET>
                    <p>
                        which can be defined using the Visitor pattern: 
                    </p>
                    <CODE_SNIPPET>
                        void foo(Bar* bar) {
                           // Some code where x, y, z are defined
                           // ...
                           DoSomethingVisitor visitor(x, y, z);
                           bar.accept(visitor);
                        }
                    </CODE_SNIPPET>
                </EXTRA>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Casting">
            <SUMMARY>
                In general, avoid designs that require casting.
                You may use <code>static_cast</code> when necessary, but avoid <code>const_cast</code> and <code>reinterpret_cast</code>.
                C-casts should be avoided and are highly discouraged.
            </SUMMARY>
            <BODY>
                <SUBSECTION title="Why not C style casts?">
                    <p>The main reason is that classic C casts make no distinction between what we call
                       <code>static_cast&lt;&gt;()</code>, <code>reinterpret_cast&lt;&gt;()</code>, <code>const_cast&lt;&gt;()</code>,
                       and <code>dynamic_cast&lt;&gt;()</code>. These four things are completely different.
                    </p>
                            
                    <p>A <code>static_cast&lt;&gt;()</code> is usually safe. There is a valid conversion in the language,
                       or an appropriate constructor that makes it possible. The only time it's a bit risky
                       is when you cast down to an inherited class; you must make sure that the object is a
                       actually the descendant that you claim it is, by means external to the language
                       (like a flag in the object). A <code>dynamic_cast&lt;&gt;()</code> is safe as long as the result is
                       checked (pointer) or a possible exception is taken into account (reference).
                    </p>
                    
                    <p>A <code>reinterpret_cast&lt;&gt;()</code> (or a <code>const_cast&lt;&gt;()</code>) on the other hand is always dangerous. 
                       You tell the compiler: "trust me: I know this doesn't look like a foo (this looks as if it isn't mutable), but it is".</p>
                                    
                    <p>The first problem is that it's almost impossible to tell which one will occur in a C-style cast without looking at large and 
                       disperse pieces of code and knowing all the rules.</p>
                    <p>For example, what does this mean?:
                       <BAD_CODE_SNIPPET>
                           x = (T)y;
                       </BAD_CODE_SNIPPET>
                       We don't know. It depends on the type <code>T</code> and the types of <code>x</code> and <code>y</code>.
                           <code>T</code> could be the name of a class,
                       a typedef, or maybe a template parameter. Maybe <code>x</code> and <code>y</code> are scalar variables and <code>(T)</code> represents a
                       value conversion. Maybe <code>x</code> is of a class derived from <code>y</code>'s class and <code>(T)</code> is a downcast.
                           Maybe <code>x</code> and
                       <code>y</code> are unrelated pointer types. Because the C-style cast <code>(T)</code> can be used to express many logically
                       different operations, the compiler has only the barest chance to catch misuses. For the same reason,
                       a programmer may not know exactly what a cast does. This is sometimes considered an advantage by
                       novice programmers and is a source of subtle errors when the novice guessed wrong.
                   </p>
 
                </SUBSECTION>
                <SUBSECTION title="What good is static_cast?">
                <p>
                    The C++ casts give programmers a chance to state their intentions
                    more clearly and allow compilers to catch errors early. For example:
                </p>
                
                <CODE_SNIPPET>
int a = 7;
double* p1 = (double*) &amp;a; // ok (but a is not a double)
double* p2 = static_cast&lt;double*&gt;(&amp;a); // error
double* p2 = reinterpret_cast&lt;double*&gt;(&amp;a) // ok: I really mean it

const int c = 7;
int* q1 = &amp;c; // error
int* q2 = (int*)&amp;c; // ok (but *q2=2; is still invalid code and may fail)
int* q3 = static_cast&lt;int*&gt;(&amp;c); // error: static_cast doesn't cast away const
int* q4 = const_cast&lt;int*&gt;(&amp;c); // I really mean it
                 </CODE_SNIPPET>
                <BLOCKQUOTE>
                 <p>
                     A secondary reason for introducing the new-style cast was that C-style casts are very hard to spot
                     in a program. For example, you can't conveniently search for casts using an ordinary editor or
                     word processor. This near-invisibility of C-style casts is especially unfortunate because they
                     are so potentially damaging. An ugly operation should have an ugly syntactic form. That observation
                     was part of the reason for choosing the syntax for the new-style casts. A further reason was for
                     the new-style casts to match the template notation, so that programmers can write their own casts,
                     especially run-time checked casts.
                </p>
                <p>
                    Maybe, because <code>static_cast</code> is so ugly and so relatively hard to type, you're more likely to think
                     twice before using one? That would be good, because casts really are mostly avoidable in modern C++.
                </p>
                <CITE>[Source: <a href="http://www.stroustrup.com/bs_faq2.html">Bjarne Stroustrup</a>]</CITE>
                </BLOCKQUOTE>
                </SUBSECTION>

                <SUBSECTION title="How to use dynamic_cast">
                  <p>
                    The beauty of <code>dynamic_cast</code> is that you can check the type of data at runtime (RTTI).
                    So remember to check that your casting was done successfully. 
                  </p>

                  <p>Don't do this.</p>
                  <BAD_CODE_SNIPPET>
void foo(Base* b1)
{
   Derived* d = dynamic_cast&lt;Derived*&gt;(b1);
   d->DoSomething();
}
                  </BAD_CODE_SNIPPET>

                  <p>You should be checking the success of the casting like this</p>
                  <CODE_SNIPPET>
void foo(Base* b1)
{
   if(Derived* d = dynamic_cast&lt;Derived*&gt;(b1))
   {
      d->DoSomething();
   }
}
                  </CODE_SNIPPET>

                </SUBSECTION>
                <DECISION>
                    <ul>
                        <li>
                            Try to avoid casts.
                            The need for casts may be a hint that too much type information was lost somewhere.
                        </li>
                        <li>
                            Use <code>static_cast</code> to explicitly convert values between different types.
                            <code>static_cast</code>s are useful for up-casting pointers in an inheritance hierarchy.
                        </li>
                        <li>
                            Avoid <code>const_cast</code>.
                            (Possibly use <code>mutable</code> member variables instead.)
                            <code>const_cast</code> may be used to adapt to const-incorrect interfaces that you cannot (get) fix(ed).
                        </li>
                        <li>
                            <code>reinterpret_cast</code>s are powerful but dangerous.
                            Rather try to avoid them.
                            Code that requires a <code>reinterpret_cast</code> should document the aliasing implications.
                            (<a href="http://en.cppreference.com/w/cpp/language/reinterpret_cast">reinterpret_cast on cppreference.com</a>)
                        </li>
                    </ul>
               </DECISION>
                <EXTRA>
                    For the dangers of <code>reinterpret_cast</code> consider:
                    <BAD_CODE_SNIPPET>
                        std::uint32_t fun()
                        {
                           std::uint32_t binary = 0;
                           reinterpret_cast&lt;float &amp;&gt;(binary) = 1.f;
                           return binary; // the return value is undefined, according to the C++ standard
                        }
                    </BAD_CODE_SNIPPET>
                    The following is better, but still undefined behavior according to the type aliasing rules:
                    <CODE_SNIPPET>
                        std::uint32_t fun()
                        {
                           float value = 1.f;
                           return reinterpret_cast&lt;std::uint32_t &amp;&gt;(value); // this returns 0x3f800000 on x86
                        }
                    </CODE_SNIPPET>
                    In case of doubt, prefer not to use <code>reinterpret_cast</code> in order to avoid mistakes.
                </EXTRA>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Variable-Length Arrays and alloca()">
            <SUMMARY>
                Don't use variable-length arrays or <code>alloca()</code>.
            </SUMMARY>
            <BODY>
                <PROS>
                    Stack-allocated objects avoid the overhead of heap allocation.
                    Variable-length arrays and <code>alloca</code> allow variably-sized stack allocations, whereas all other stack allocations in C++ only allow fixed-size objects on the stack.
                </PROS>
                <CONS>
                    Variable-length arrays are part of C but not Standard C++.
                    <code>alloca</code> is part of POSIX, but not part of Standard C++.
                </CONS>
                
                <DECISION>
                    Use STL containers instead.
                    If you really need to improve the performance consider using a custom allocator for the containers.
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Increment and Decrement Operators" nobutton="yes">
            <SUMMARY>
                Wherever applicable, prefer the prefix form of the increment (<code>++i</code>) and decrement 
                (<code>--i</code>) operators because it has simpler semantics.
            </SUMMARY>
        </STYLEPOINT>

        <STYLEPOINT title="assert">
          <SUMMARY>
            Use of the <code>assert()</code> macro for aborting the program execution if a test condition is met is strongly discouraged in STAR code.
          </SUMMARY>
          <BODY>
               <DEFINITION>
                 <a href="http://en.cppreference.com/w/cpp/error/assert"><code>assert</code></a> checks if its argument compares equal to zero.
                 If so, it calls <code>std::abort</code> and prints out standard diagnostic information on the standard error output.
               </DEFINITION>
               <DECISION>
                   <p>
                  In STAR software, plainly aborting a program should be avoided.
                  Given the size and complexity of our software, it is mandatory to signal an error and propagate the <code>kStFatal</code> error flag.
                  Unless your Maker is a fundamental and/or base maker (DAQ detecting a corruption, DB finding an unlikely condition which should really never happen, IO maker not able to stream, ...),
                  the use of <code>assert()</code> is prohibited as a single detector sub-system error shall never lead to an entire
                  chain abort. The use of clear messages with level <code>FATAL</code> is emphasized.
               </p>
               </DECISION>
         </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Loops and Switch Statements">
            <SUMMARY>
                <p>
                    If not conditional on an enumerated value, switch statements should always have a <code>default</code> case.
                    Empty loop bodies should use <code>{}</code> or <code>continue</code>. Declare variable in <code>if</code> and <code>while</code> statement conditions to pin
                    the lifetime of the variable to the intended scope (see below). 
                </p>
            </SUMMARY>
            <BODY>
                <p>If not conditional on an enumerated value, switch statements
                    should always have a <code>default</code> case (in the case of
                    an enumerated value, the compiler will warn you if any values
                    are not handled).  If the default case should never execute, you should print a clear log message with level 
                    <code>FATAL</code> and propagate up a <code>kStFatal</code> error flag.
                </p>
                <CODE_SNIPPET>
                    switch (value) {
                    case 0: {
                       ...      // Minimum 2 space indent
                       break;
                     }
                    case 1: {
                          ...
                       break;
                     }
                    default: {
                       LOG_FATAL&lt;&lt;"StMyMaker - a switch case reached a default case that should never have been reached"&lt;&lt;enmd;
                       return kStFatal;
                     }
                    }
                </CODE_SNIPPET>
                <p>
                    Empty loop bodies should use <code>{}</code> or
                    <code>continue</code>, but not a single semicolon.
                </p>
                <CODE_SNIPPET>
                    while (condition) {
                       // Repeat test until it returns false.
                    }
                    for (int i = 0; i &lt; someNumber; ++i) {}  // Good — empty body.
                    while (condition) continue;  // Good — continue indicates no logic.
                </CODE_SNIPPET>
                <BAD_CODE_SNIPPET>
                    while (condition);  // Bad — looks like part of do/while loop.
                </BAD_CODE_SNIPPET>

                <p>
                   Declare variable in <code>if</code> and <code>while</code> statement conditions to pin the lifetime of the variable to the intended scope.
                   For example:
                   <CODE_SNIPPET>
                       if (MyType* var = something->getMore())
                       {
                         if (MyNext* next = var->getNext())
                         {
                           ...
                         }
                       }
                   </CODE_SNIPPET>
                   instead of 
                   <BAD_CODE_SNIPPET>
                       MyType* var = nullptr;
                       MyType* next = nullptr;
                       if (var = something->getMore())
                       {
                         if (next = var->getNext())
                         {
                           ...
                         }
                       }
                   </BAD_CODE_SNIPPET>
                   similarly for <code>while</code> conditional statements.
                </p>
            </BODY>
        </STYLEPOINT>

        <STYLEPOINT title="Range-for Statement" cpp11="yes">
          <SUMMARY>
            Range-for loops are useful and should be used. Use reference to elements  (or <code>const</code>) in range-for statements especially when 
            dealing with large objects. Prefer ordinary loops when you need the index information.
          </SUMMARY>
          <BODY>
            <DEFINITION>
              C++ syntax is extended to support easier iteration over a list of elements. For example:  
              <CODE_SNIPPET>
                int main()
                {
                   vector&lt;int&gt; v {1,2,3,4,5};

                   for(auto&amp; i:v)  // reference to element
                   {
                      cout &lt;&lt; i &lt;&lt; endl;
                      i +=1;        // modifies element value
                   }

                   for(auto i:v)   // copy of element
                   {
                      cout &lt;&lt; i &lt;&lt; endl;
                   }
                   return 0;
                }
              </CODE_SNIPPET>
              Range-for statements work for any type where <code>begin()</code> and <code>end()</code> are defined to return iterators.  
            </DEFINITION>

            <PROS>
              The use of range-for loops increases code readability. 
            </PROS>

            <CONS>
              <p> Programmers often need both, the elements of an iterable collection and its index. This is not directly supported in C++11. </p>
              <p> Unless optimized away by compiler, using a copy of element could come at a performance cost if the element type is large. </p>
            </CONS>

            <DECISION>
              <p>Range-for loops are useful and should be used.</p>
              <p>Ordinary loops should be preferred when programmer needs the element index. Avoid having your own counter.</p>
              <p>Using reference to elements is encouraged when dealing with large objects. Use <code>const</code> reference when you don't need to modify the object state.</p>
              <p>Note that when dealing with proxy references <code>auto&amp;</code> does not work, <code>auto&amp;&amp;</code> should be used instead.</p>
            </DECISION>

          </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Integer Types" cpp11="yes">
            <SUMMARY>
                Per default, use <code>int</code> if you need an integer type. If you need to guarantee a specific size use the new extended integer
                types defined in <code>&lt;cstdint&gt;</code>.
            </SUMMARY>
            <BODY>
                <p>
                    There are five standard signed integer types in C++:
                    <CODE_SNIPPET>
                    signed char
                    short int
                    int
                    long int
                    long long int
                    </CODE_SNIPPET>
                   and five unsigned integer types
                   <CODE_SNIPPET>
                    unsigned char
                    unsigned short int
                    unsigned int
                    unsigned long int
                    unsigned long long int
                    </CODE_SNIPPET>

                    The C++ standard only loosely specifies the sizes of its built-in integer types and only guarantees that their sizes are:
                    <CODE_SNIPPET>
                        signed char = unsigned char ≤ short int = unsigned short int ≤ int = unsigned int ≤ long int = unsigned long int ≤ long
                        long int = unsigned long long int
                    </CODE_SNIPPET>
                </p>
                <CPP11 title="Extended Integer Types">
                    <p>Already implemented by many compilers the C++11 standard makes these types now official.</p>
                    
                    Signed integer type with width of exactly 8, 16, 32 and 64 bits respectively with no padding
                    bits and using 2's complement for negative values (provided only if the implementation directly
                    supports the type).
                    <CODE_SNIPPET>
                        int8_t
                        int16_t
                        int32_t
                        int64_t
                    </CODE_SNIPPET>
                    Fastest signed integer type with width of at least 8, 16, 32 and 64 bits respectively.
                    <CODE_SNIPPET>
                        int_fast8_t
                        int_fast16_t
                        int_fast32_t
                        int_fast64_t
                    </CODE_SNIPPET>
                    Smallest signed integer type with width of at least 8, 16, 32 and 64 bits respectively.
                    <CODE_SNIPPET>
                        int_least8_t
                        int_least16_t
                        int_least32_t
                        int_least64_t
                    </CODE_SNIPPET>
                    Maximum width integer type.
                    <CODE_SNIPPET>
                        intmax_t
                    </CODE_SNIPPET>
                    Integer type capable of holding a pointer.
                    <CODE_SNIPPET>
                        intptr_t
                    </CODE_SNIPPET>
                    All types exist also as unsigned version in which case they are preceded by a <code>u</code>.
                </CPP11>

                <p>
                    While these types are sufficient for most tasks, there are times where the precise size has to be defined.
                    In this case consider one of the <a href="http://en.cppreference.com/w/cpp/header/cstdint">integer types in <code>&lt;cstdint&gt;</code></a>.
                    Already before C++11 these types were implemented in most compilers but C++11 makes it official. Three types are defined in header
                    <code>&lt;cstdint&gt;</code>: Exact-Width Types, Minimum-Width Types, and Fastest Minimum-Width Types.
                </p>
                <SUBSECTION title="Exact-Width Types">
                    <p>This set identify types with precise sizes. The general form is <code>int</code>N<code>_t</code> for signed types
                        and <code>uint</code>N<code>_t</code> for unsigned types,
                    with N indicating the number of bits. Note, however, that not all systems can support all the types. For example, there
                    could be a system for which the smallest usable memory size is 16 bits; such a system would not support the
                        <code>int8_t</code> and <code>uint8_t</code> types.</p>
               </SUBSECTION>
                <SUBSECTION title="Minimum-Width Types">
                    <p>The minimum-width types guarantee a type that is at least a certain number of bits in size. These types always exist.
                    For example, a system that does not support 8-bit units could define <code>int_least_8_t</code> as a 16-bit type.</p>
                </SUBSECTION>
                <SUBSECTION title="Fastest Minimum-Width Types">
                    <p>For a particular system, some integer representations can be faster than others. For example, <code>int_least16_t</code> might be
                    implemented as <code>short</code>, but the system might do arithmetic faster using type <code>int</code>. So <code>&lt;cstdint&gt;</code>
                    also defines the fastest
                    type for representing at least a certain number of bits. These types always exist. In some cases, there might be
                    no clear-cut choice for fastest; in that case, the system simply specifies one of the choices.</p>
                </SUBSECTION>
                <DECISION>
                    In general the standard integer types should be used since they are typically also the “fastest” types on the respective architecture.
                    In cases where the exact size matters, e.g. unpacking of raw data the extended types the extended integer types can be used. The use
                    of ROOT types is discouraged unless it is absolute necessary (see discussion under <a href="#ROOT_Related_Issues">"ROOT Related Issues"</a>).
                </DECISION>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="Portability">
            <SUMMARY>
                Take extra care of the code portability. Bear in mind problems of
                printing, comparisons, and structure alignment related to 
                32-bit and 64-bit data representations .
            </SUMMARY>
            <BODY>
                <p> 
                    Below we give a list (incomplete) of possible portability 
                    issues:
                </p> 
                <ul>
                    <li> <code>printf()</code> specifiers for some types are
                        not cleanly portable between 32-bit and 64-bit
                        systems. </li>
                    <li> Remember that <code>sizeof(void *)</code> !=
                        <code>sizeof(int)</code>.  Use <code>intptr_t</code> if
                        you need a pointer-sized integer.
                    </li>
                    <li> You may need to be careful with structure alignments,
                        particularly for structures being stored on disk. </li>
                    <li> The data memory representation is computer specific and
                        not defined by C++. The terms endian and endianness, refer 
                        to how bytes of a data word are ordered within memory.
                        Big endian store bytes from the highest to the lowest, 
                        Little endian from the lowest to the highest.
                    </li>
                </ul>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="0 and nullptr" cpp11="yes">
          <SUMMARY>
                C++ 11 introduces the literal nullptr. It is of type std::nullptr_t and it converts implicitly to all pointer types. nullptr is a prvalue (i.e. pure rvalue, you e.g. cannot take its address)
            Use <code>0</code> for integers, <code>nullptr</code> for pointers,
            and <code>'\0'</code> for chars.
          </SUMMARY>
          <BODY>
            <p> 
              <code>nullptr</code> is a pointer literal of type <code>std::nullptr_t</code>. On the other hand, <code>NULL</code> 
              is a macro equivalent the integer <code>0</code>. Using <code>NULL</code> could bring to unexpected problems. For example imagine you have the following two function declarations:
              <BAD_CODE_SNIPPET>
                void function(int number);
                void function(char *name);

                function( NULL );
              </BAD_CODE_SNIPPET>
              Because <code>NULL</code> is <code>0</code>, and <code>0</code> is an integer,
              the first version of <code>function</code> will be called instead.
              In C++11, <code>nullptr</code> is a new keyword that can (and should!) be used to represent <code>NULL</code> pointers.
            </p>
          </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="sizeof">
            <SUMMARY>
                Prefer <code>sizeof(<var>varname</var>)</code> to
                <code>sizeof(<var>type</var>)</code>.
            </SUMMARY>
            <BODY>
                <p>
                    Use <code>sizeof(<var>varname</var>)</code>
                    when you take the size of a particular variable.
                    <code>sizeof(<var>varname</var>)</code> will update
                    appropriately if someone changes the variable type
                    either now or later.
                    You may use <code>sizeof(<var>type</var>)</code>
                    for code unrelated to any particular variable,
                    such as code that manages an external or internal
                    data format where a variable of an appropriate C++ type
                    is not convenient.
                </p>
                <p>
                    <CODE_SNIPPET>
                        Struct data;
                        memset(&amp;data, 0, sizeof(data));
                    </CODE_SNIPPET>
                    <BAD_CODE_SNIPPET>
                        memset(&amp;data, 0, sizeof(Struct));
                    </BAD_CODE_SNIPPET>
                    <CODE_SNIPPET>
                        if (rawSize &lt; sizeof(int)) {
                           logMessage &lt;&lt; "compressed record not big enough for count: " &lt;&lt; rawSize;
                        }
                    </CODE_SNIPPET>
                </p>
            </BODY>
        </STYLEPOINT>
        
        <STYLEPOINT title="auto" cpp11="yes">
            <SUMMARY>
                If the compiler is able to deduce the type of a variable from its
                initialization, you don't need to provide the type. This is achieved by using the
                <code>auto</code> keyword.
                <p>
                Use <code>auto</code> to avoid type names that are just clutter.
                Continue to use manifest type declarations when it helps readability,
                and never use <code>auto</code> for anything but local variables.
                </p>
                <p>
                Use <code>auto</code> against verbosity, not consistency. In cases where the rhs
                expression is an integer or floating point literal the use of auto is strongly discouraged.
                </p>
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    In C++11, a variable whose type is given as <code>auto</code> will be given
                    a type that matches that of the expression used to initialize
                    it. You can use <code>auto</code> either to initialize a
                    variable by copying, or to bind a reference.
                    <CODE_SNIPPET>
                        vector&lt;string&gt; names;
                        ...
                        auto name1 = names[0];  // Makes a copy of names[0].
                        const auto&amp; name2 = names[0];  // name2 is a reference to names[0].
                    </CODE_SNIPPET>
                </DEFINITION>
                <PROS>
                    <p>
                        C++ type names can sometimes be long and cumbersome,
                        especially when they involve templates or namespaces. In a statement like
                        <BAD_CODE_SNIPPET>
                            map&lt;string, string&gt;::iterator itr = address_book.begin();
                        </BAD_CODE_SNIPPET>
                        the return type is hard to read, and obscures the primary
                        purpose of the statement. Changing it to
                        <CODE_SNIPPET>
                            auto itr = address_book.begin();
                        </CODE_SNIPPET>
                        makes it more readable.
                    </p>
                    <p>
                        Without <code>auto</code> we are sometimes forced to write a
                        type name twice in the same expression, adding no value
                        for the reader, as in
                        <BAD_CODE_SNIPPET>
                            diagnostics::ErrorStatus* status = new diagnostics::ErrorStatus("xyz");
                        </BAD_CODE_SNIPPET>
                    </p>
                    <p>
                        Using <code>auto</code> makes it easier to use intermediate
                        variables when appropriate, by reducing the burden of writing
                        their types explicitly.
                        <CODE_SNIPPET>
                            auto status = new diagnostics::ErrorStatus("xyz");
                        </CODE_SNIPPET>
                    </p>
                </PROS>
                <CONS>
                    <p>Sometimes code is clearer when types are manifest, especially when
                        the initialization of a variable depends on functions/variables that were declared
                        far away. In an expression like
                        <BAD_CODE_SNIPPET>
                            auto i = xValue.Lookup(key);
                        </BAD_CODE_SNIPPET>
                        it may not be obvious what <code>i</code>'s type is, if <code>x</code>
                        was declared hundreds of lines earlier.
                    </p>
                    
                    <p>Programmers have to understand the difference between <code>auto</code>
                        and <code>const auto&amp;</code> or they'll get copies when
                        they didn't mean to.
                    </p>
                    
                    <p>The interaction between <code>auto</code> and C++11
                        brace-initialization can be confusing. The declarations
                        <BAD_CODE_SNIPPET>
                            auto xValue(3);  // Note: parentheses.
                            auto yValue{3};  // Note: curly braces.
                        </BAD_CODE_SNIPPET>
                        mean different things — <code>xValue</code> is
                        an <code>int</code>, while <code>yValue</code> is
                        an <code>initializer_list</code>. The same applies to other
                        normally-invisible proxy types.
                    </p>
                    
                    <p>If an <code>auto</code> variable is used as part of an
                        interface, e.g. as a constant in a header, then a programmer
                        might change its type while only intending to change its
                        value, leading to a more radical API change than intended.</p>
                    
                    <p>
                        There is a certain danger using <code>auto</code> with numerical literals.
                        <BAD_CODE_SNIPPET>
                            auto i = 3;      // i is an int
                            auto x = 10;     // x is an int
                            auto y = 10.2;   // y is an double
                            auto l = 2;      // l is an int
                        </BAD_CODE_SNIPPET>
                        This might not be what was intended. To make it clear to the compiler
                        one would need to be more explicit:
                        <BAD_CODE_SNIPPET>
                            auto i = 3U;      // i is an unsigned int
                            auto x = 10F;     // x is a float
                            auto y = 10.2L;   // y is a long double
                            auto l = 2LL;     // l is an long long
                        </BAD_CODE_SNIPPET>
                        Nothing is gained using the suffix notation. If the type has to be explicitly defined
                        than it is much clearer to write:
                        <CODE_SNIPPET>
                            unsigned int i = 3;
                            float x = 10;
                            long double y = 10.2;
                            long long l = 2;
                        </CODE_SNIPPET>
                    </p>
                </CONS>
                <DECISION>
                    <p><code>auto</code> is permitted for local variables only.
                        Do not use <code>auto</code> for file-scope or namespace-scope
                        variables, or for class members. Do not use <code>auto</code> for numeric literals.
                        Never assign a braced initializer list to an <code>auto</code>-typed variable.</p>
                </DECISION>
            </BODY>
        </STYLEPOINT>

        <STYLEPOINT title="Non-member begin() and end()" cpp11="yes">
            <SUMMARY>
                The non-member <code>begin()</code> and <code>end()</code> functions are a new addition to the standard library,
                promoting uniformity, consistency and enabling more generic programming. They work with
                all STL containers, but more than that they are overloadable, so they can be extended to
                work with any type. Overloads for C-like arrays are also provided.
                The use of non-member <code>begin()</code>  and <code>end()</code> is encouraged.
            </SUMMARY>
            <BODY>
                <DEFINITION>
                    In STL all containers have a non-static member <code>begin()</code> and <code>end()</code> methods that return an iterator
                    to the beginning and the end of the container. Therefor iterating over a container could look like this:
                    <CODE_SNIPPET>
                        std::vector&lt;int&gt; v;
                        for(auto it = v.begin(); it != v.end(); ++it)
                           std::cout &lt;&lt; *it &lt;&lt; std::endl;
                    </CODE_SNIPPET>
                    The problem here is that not all user-defined containers have <code>begin()</code> and <code>end()</code>, which makes them
                    impossible to use with the STL algorithms or any other user-defined template function that requires
                    iterators. That is even more problematic when using C arrays.
                    The non-member <code>begin()</code> and <code>end()</code> methods are extensible, in the sense they can be overloaded for
                    any type (including C arrays).
                    <CODE_SNIPPET>
                        std::vector&lt;int&gt; v;
                        for(auto it = begin(v); it != end(v); ++it)
                           std::cout &lt;&lt; *it &lt;&lt; std::endl;
                    </CODE_SNIPPET>
                    To adopt any custom container all one must do is create your own iterator that supports <code>*</code>,
                    prefix increment (<code>++itr</code>) and <code>!=</code> .
                </DEFINITION>
                <DECISION>
                    The use of the non-member version of <code>begin()</code> and <code>end()</code> allows one to write very generic methods and is hence encouraged.
                </DECISION>

            </BODY>
        </STYLEPOINT>

<STYLEPOINT title="static_assert and type traits" cpp11="yes">
    <SUMMARY>
        <code>static_assert()</code> performs an assertion check at compile-time.
        Type traits and <code>static_assert</code> is mostly for
        template class developer . Since the use of templates in STAR is minimal, these new C++11
        features will be rarely used, if at all. There’s no argument against using this feature
        if needed.
   </SUMMARY>
    <BODY>
        <DEFINITION>
            <code>static_assert()</code> performs an assertion check at compile-time. If the assertion is true, nothing happens. If the assertion is false, the compiler displays the specified error message.

            <CODE_SNIPPET>
                    template &lt;typename T, size_t Size&gt;
                    class MyVector
                    {
                       static_assert(Size &gt; 3, "Size is too small");
                       T points[Size];
                    };
                    
                    int main()
                    {
                       MyVector &lt;int, 16&gt; a1;
                       MyVector &lt;double, 2&gt; a2;  // will produce compile error
                       return 0;
                    }
            </CODE_SNIPPET>
            The form of the output depends on the platform. One the Mac using LLVM it prints:
            <CODE_SNIPPET>
                sassert.cpp:12:5: error: static_assert failed "Size is too small."
                static_assert(Size > 3, "Size is too small.");
            </CODE_SNIPPET>
            Note that since static_assert is evaluated at compile time, it cannot be used to
            check assumptions that depends on run-time values.

            <p>
                <code>static_assert()</code> becomes more useful when used together with type traits. These are a
                series of classes that provide information about types at compile time. They are available
                in the <code>&lt;type_traits&gt;</code> header. There are several categories of classes in this header:
                    helper classes, for creating compile-time constants, type traits classes, to get
                    type information at compile time, and type transformation classes, for getting new
                    types by applying transformation on existing types.
            </p>
            <CODE_SNIPPET>
                template &lt;typename T1, typename T2&gt;
                auto add(T1 t1, T2 t2) -&gt; decltype(t1 + t2)
                {
                   static_assert(std::is_integral&lt;T1&gt;::value, "Type T1 must be integral");
                   static_assert(std::is_integral&lt;T2&gt;::value, "Type T2 must be integral");
                   return t1 + t2;
                }
            </CODE_SNIPPET>

        </DEFINITION>
        <DECISION>
            There’s no argument against using this feature if needed. Note that <code>static_assert()</code>
            does not violate STAR’s messaging scheme since the assert error messages are printed
            at compile not run time.

        </DECISION>
        
    </BODY>
</STYLEPOINT>

        <STYLEPOINT title="Rvalue Reference and Move Semantics" cpp11="yes">
          <SUMMARY>
             Rvalue reference are used to achieve move semantics and perfect forwarding. See <a href="#Move_Constructor_and_Assignment_Operator"> Move Constructor and Assignment Operator</a>
             for the guideline on the move semantics.
          </SUMMARY>
            <BODY>
                <DEFINITION>
                  <CPP11 title="rvalue Reference">
                    One can find multiple rules of thumb for recognizing the lvalueness or rvalueness of an object. For our purposes, the following are sufficient:
                    <p>If you can take its address using the built-in address-of operator (&amp;) then it is an lvalue, otherwise, it is an rvalue.</p>
                    <p>Another useful rule of thumb that is useful but not strictly correct is the <a href="http://thbecker.net/articles/rvalue_references/section_05.html">if-it-has-a-name rule</a>: 
                      if it has a name then it is an lvalue, otherwise, it is an rvalue.</p>

                    <p>
                    Rvalue reference is designated with an &amp;&amp; as opposed to &amp; for lvalue reference. 
                    Here is an example of function overloading to handle lvalue and rvalue arguments separately:  
                    <CODE_SNIPPET>
                      #include &lt;cstddef&gt;
                      int foo()
                      {
                         return 5;
                      }

                      void print(int const&amp; x)
                      {
                         cout &lt;&lt; __PRETTY_FUNCTION__ &lt;&lt; endl;
                         cout &lt;&lt; x &lt;&lt; endl;
                      }

                      void print(int&amp;&amp; x)
                      {
                         cout &lt;&lt; __PRETTY_FUNCTION__ &lt;&lt; endl;
                         cout &lt;&lt; x &lt;&lt; endl;
                      }

                      int main()
                      {
                         std::cout &lt;&lt; "Hello, World!\n";

                         int x =6;
                         print(x);  // call print on an lvalue
                         print(foo()); // call print on an rvalue
                      }
                    </CODE_SNIPPET>
                    Now this looks cool. However, the real power of the ability to distinguish between rvalues and lvalues in C++11 is to enable two things: 
                    1) move semantics 2) perfect forwarding. 
                    </p>
                  </CPP11>

                  <p>
                  The move semantics allow to get rid of expensive copies from temporary (rvalue) objects when a move is intended. Now that we can 
                  detect temporary objects using rvalue references we can overload the copy/assignment functions to do the less expensive move from the temporary object 
                  by simply pointing the current object's pointers to the temporary object's resources and nullifying the latter's pointers. To add to the multitude of 
                  examples of move semantics implementation here is one:  
                  </p>
                  
                  <CODE_SNIPPET>
                  #include &lt;cstddef&gt;
                  
                  class dataHandler
                  {
                  private:
                     int  mNumberOfElements;
                     int* mData;
                  
                  public:
                     dataHandler(int n=10): mNumberOfElements(n), mData(new int[mNumberOfElements]) {cout &lt;&lt; __PRETTY_FUNCTION__ &lt;&lt; endl;}
                  
                     // copy constructor
                     dataHandler(const dataHandler&amp; x): mNumberOfElements(x.mNumberOfElements), mData(new int[x.mNumberOfElements])
                     {
                        cout &lt;&lt; __PRETTY_FUNCTION__ &lt;&lt; endl;
                        for(int i=0;i&lt;this->mNumberOfElements;i++){ this->mData[i] = x.mData[i]; }
                     }
                  
                     // copy assignment operator
                     dataHandler&amp; operator=(const dataHandler&amp; rhs)
                     {
                        cout &lt;&lt; __PRETTY_FUNCTION__ &lt;&lt; endl;
                  
                        if(this == &amp;rhs) return *this;
                        if(this.mNumberOfElements != rhs.mNumberOfElements) 
                        {
                           // this should never happen and should throw an exception.
                           // we will just terminate the program instead of throwing an exception in this demo example.
                           exit(1);
                        }

                        for(int i=0;i&lt;this->mNumberOfElements;i++){ this->mData[i] = x.mData[i]; }
                        return *this;
                     }
                  
                     // move constructor
                     dataHandler(dataHandler&amp;&amp; x)
                     {
                        cout &lt;&lt; __PRETTY_FUNCTION__ &lt;&lt; endl;
                        this->mData = x.mData;
                        this->mNumberOfElements  = x.mNumberOfElements;
                        x.mData = nullptr;
                     }
                  
                     // move assignment operator
                     dataHandler&amp; operator=(dataHandler&amp;&amp; rhs)
                     {
                        cout &lt;&lt; __PRETTY_FUNCTION__ &lt;&lt; endl;
                  
                        if(this == &amp;rhs) return *this;
                  
                        this->mData = rhs.mData;
                        this->mNumberOfElements  = x.mNumberOfElements;
                        rhs.mData = nullptr;
                  
                        return *this;
                     }
                  
                     ~dataHandler(){ cout &lt;&lt; __PRETTY_FUNCTION__ &lt;&lt; endl; if(mData) delete mData;}
                  
                     inline int data() const { return *mData;}
                  };
                  
                  dataHandler get_a_dataHandler()
                  {
                     dataHandler t(6);
                     return t;
                  }
                  
                  int main()
                  {
                     cout &lt;&lt; "Testing move semantics..." &lt;&lt; endl;
                     dataHandler t0;
                     t0 = get_a_dataHandler(); // should call move assignment operator.
                   
                     dataHandler t1(get_a_dataHandler()); // should call move constructor (unless optimized away by the compiler (lookup RVO and copy elision)).

                     return 0;
                  }
                  </CODE_SNIPPET>
                  
                  An rvalue reference itself is not necessarily an rvalue. For example, inside the move constructor the variable x is an 
                  rvalue reference, but it is an lvalue (you can take its address, it has a name). This case is important when one 
                  wants to construct base classes in a move function of the derived class. The base class move function should be invoked 
                  and this can be achieved by statically casting the variable x to an rvalue reference, i.e. hiding its name which can 
                  be achieved using std::move.
                  
                  <BAD_CODE_SNIPPET>
                  Derived(Derived&amp;&amp; rhs) 
                    : Base(rhs) // wrong: rhs is an lvalue
                  {
                    // Derived-specific stuff
                  }
                  
                </BAD_CODE_SNIPPET>
                  <CODE_SNIPPET>
                  Derived(Derived&amp;&amp; rhs) 
                    : Base(std::move(rhs)) // good, calls Base(Base&amp;&amp; rhs)
                  {
                    // Derived-specific stuff
                  }
                  </CODE_SNIPPET>
                  
                  std::move hides the name of its arguments (static casting it to an rvalue reference).  

                  <CPP11 title ="Perfect Forwarding">
                    There is one subtlety with rvalues and deduced types. The rvalueness/lvalueness of a deduced type follows that of the initializer. For example, 
                    in a function template:  

                    <CODE_SNIPPET>
                    template&lt;typename T&gt;
                    void print(T&amp;&amp; x) { cout &lt;&lt; x &lt;&lt; endl;}
                    </CODE_SNIPPET>

                    So calling print on a lvalue makes <code>x</code> an lvalue reference, same if <code>x</code> is an rvalue. Now when does this matter? It doesn't matter inside <code>print</code> itself 
                    since <code>x</code> is an lvalue there anyway. It matters when you want to pass <code>x</code> to another function, do you pass it as an lvalue (just <code>x</code>) or hide its 
                    name using <code>std::move</code>? The answer obviously depends on the nature of <code>x</code>, you want to preserve that. This can be achieved using <code>std::forward</code>. std:forward passes
                    rvalue references as rvalues and lvalue references as lvalues.  
                  </CPP11>
                </DEFINITION>
                <DECISION>
                  <p>Strive to define your move semantics so that they cannot throw exceptions and declare them so using <code>noexcept</code> specifier.  </p>
                  <p>Use <code>std::move</code> to pass argument to base classes in move constructor and assignment operator.  </p>
                  <p>Use <code>std:forward</code> to forward arguments to classes constructors in templated functions or classes.  </p>
                  <p>Remember that an rvalue reference is not necessarily an rvalue itself.  </p>
                  <p>Take advantage of compilers Return Value Optimization (RVO)/elision, don't be afraid to return by value.</p>
                </DECISION>
              </BODY>
        </STYLEPOINT>
        
    </CATEGORY>
    
    <CATEGORY title="Exceptions to the Rules">
        <p>
            The coding conventions described above have to be followed.  However,
            like all good rules, these sometimes have exceptions.
        </p>
        
        <STYLEPOINT title="Existing Non-Conformant Code">
            <SUMMARY>
                It is permissible to deviate from the rules when dealing with code that does not
                conform to these guidelines. 
            </SUMMARY>
            <BODY>
                <p>
                    To modify code that was written to
                    specifications other than those presented by this guide, it may be necessary to deviate from these rules in order to stay consistent with
                    the local conventions in that code.  In case of doubt the original author or the person currently
                    responsible for the code should be consulted.  Remember that <em>consistency</em>
                    also includes local consistency.
                </p>
            </BODY>
        </STYLEPOINT>
    </CATEGORY>
    
    
    <PARTING_WORDS>
        <p>
            Use common sense and <em>BE CONSISTENT</em>.
        </p>
        <p>
            The point about having style guidelines is to have a common
            vocabulary of coding so people can concentrate on what the programmer
            is saying, rather than on how he/she is saying it.
        </p>
        <p>
            OK, enough writing about writing code; the code itself is much
            more interesting. Have fun!
        </p>
    </PARTING_WORDS>
    
</GUIDE>