Glotzilla Coding Conventions

Right now most of the code is written in C++. Try to follow standard C++ conventions whenever possible. Try not to do anything "fancy" or difficult to understand. Break the conventions only when it improves readability or is otherwise absolutely necessary.

Capitalization, Underscoring, etc.

• Class names - StartWithCapital
• Each separate phrase in the class name - StartsWithCapital
• Per the previous rule, don't capitalize acronyms - ex: HtmlWriter, OpenGlImage, XmlFile
• Class instances - startWithLowerCase
• Member functions - classInstance.StartWithCapital()
• Private member variables - mStartWithM
• Static member variables - sStartWithS
• Public member variables (use sparingly!) - xStartWithX
• Pseudo global member variables - gStartWithG
• Variables on the stack - start_with_lowercase and have_underscores
• C functions (use sparingly!): have_underscores()
• Member function arguments - void MyClass::MemberFunction(int argumentStartsWithNonCapital)
• namespaces use small letters and start with "glotz" - ex: glotzmd, glotzopengl
• C macros (should almost never be used) - _StartWithUnderscore
• Loop variables: i, j, k

Set, Get, Compute Accessors

All class member variables are private, unless commonly used in math functions only interact with private class members using Set...() or Get...() accessor functions. If something needs to be computed use Compute...() rather than Get...(). Public member variables are prepended by x (use sparingly). Private member variables are prepended by m. Pseudo global variables (which are references to member functions in the parent simulation class) are prepended by a g.

No true global variables

Global variables can lead to serious ambiguities and work against the object-oriented paradigm of C++. Glotzilla should contain no global variables under any circumstances.

        int NumberOfParticles = 100;
        
        int main(int argc, char **argv)
        {
                int NumberOfParticles = 200;
                std::cout << NumberOfParticles << std::endl;
        }
        
        $ 200

Of course there are a few exceptions to this rule. One example is certain static variables or enum types, which are sometimes global.

No C-style precompiler macros

Macros can be very confusing and are not type safe. Moreover, they are inherently global and violate the previous rule.

        #define NumberOfParticles 100;
        
        int main(int argc, char **argv)
        {
                int NumberOfParticles = 200;
                std::cout << NumberOfParticles << std::endl;
        }
        
        $ (Compiler error)

Note that conditional compilation macros are sometimes acceptable, although should be used sparingly since they make the code difficult to read.

#ifdef PRINT_TEMPERATURE
   my_simulation.PrintTemperature(std::cout);
#endif

In a few very select cases where they are the only solution, we do use precompiler macros in Glotzilla. One example is the serialization library, where we define macros that write necessary member functions for the programmer.

Use "glotz" namespaces

Put all class definitions in the glotzilla namespace This resolves any naming issues with other codes.

        #include <math.h>
        #include <iostream>

        namespace glotzilla
        {
                double sqrt(double tmp)
                {
                        std::cout << "USING GLOTZILLA SQRT!!!\t";
                        //use pow from math.h to calculate:
                        return pow(tmp, 1.0/2.0);
                }
        }

        int main(int argc, char **argv)
        {
                //calls the math sqrt function:
                std::cout << sqrt(36) << std::endl;                     
                //calls the glotzilla sqrt function
                std::cout << glotzilla::sqrt(36) << std::endl; 
        }

        $ 6
        $ USING GLOTZILLA SQRT!!! 6

All namespaces start with "glotz" and end in a short, descriptive name.

Class layout

Here is an example glotzilla class layout. The rules are listed below.

   namespace glotzilla
   {
      class MyClass
      {
         public:
            double GetMemberDouble();
            void SetMemberDouble(double);
            int GetMemberInt();
            void SetMemberInt(int);
            int xAccessibleInt;      //Use sparingly!
         private:
            int mMemberInt;
            double mMemberDouble;
            static float sMemberFloat;
      };
   }

Comment Using Doxygen

We use Doxygen to automatically generate documentation from class layout. You can generate either descriptive (/** ... */) or short comments (///< ...).

   namespace glotzilla
   {
      /**
      @brief A class to do nothing
      @author Your Name
      @ingroup some_group
      @note this is just an example
      */
      class MyClass
      {
         public:
            double GetMemberDouble();      ///<Returns a double
            void SetMemberDouble(double);  ///<Sets a double
            int GetMemberInt();            ///<Returns an int
            void SetMemberInt(int);        ///<Sets an int
            int xAccessibleInt;            ///<A public variable
         private:
            int mMemberInt;                ///<A private integer
            double mMemberDouble;          ///<A private double
            static float sMemberFloat;     ///<A static float
            
            /**
            @brief a private function
            @param i is an integer 
            @return some number
            
            This type of comment typically occurs in the .cpp 
            file rather than the .h file
            */
            int MyPrivateFunction(int i);
      };
   }