Palomino - Coding

©2004,2009  Jim E. Brooks   http://www.palomino3d.org

• Index
• Overview
• Coding Style
• Lua Coding Style
• Globals vs. Singletons
• Reminders

Overview of Coding

[2007/12]

Source code is written in C++. For portability, the code is written to abstract the graphics system and scene graph. Generalized C++ classes and Facade classes are used. For example, the Graph class is a Facade over an osg::Switch node.

The source code is designed to be modular and layered. Layers (in the form of Facade and Mediator C++ classes) keep the top-level of the program from becoming too dependent on drivers, graphics API, scene graph library, etc.

To catch memory corruption or uninitialized data, critical classes have a "type signature" data member which is checked in DEBUG builds.

Coding Style

[2004,2008/04]

Naming convention:

• Camel-back letters.
• Functions/methods begin with capital letter.
• Class members prefixed with "m" (or "ms" if static).
  Don't bother writing "mp"/"mr" for pointers/references (too pedantic, compiler will catch misuse).
• Static vars prefixed with "s", static members with "ms"
  whether static members begin with "s" depends on whether the fact it's shared should be exposed or concealed
• typedef TYPE value_type; declared by wrapper classes over fundamental types (OSG convention).
• Place limited-use or perilous code in "RESTRICT" sub-namespace (not "restricted" which C99 reserves).
• Singletons:
  Create a macro named GET_CLASS() for singletons (or globals that can behave as singletons).
• Globals:
  • Put widely-accessible globals in "global" namespace or put "global" in their name.

  // Alternative using a single global:
  namespace module {
  namespace global {
  
  World gWorld;
  
  } // namespace global
  } // namespace module
  

  // Alternative using a struct of globals:
  namespace module {
  struct Globals
  {
      Window mWindow;
      Gui    mGui;
  };      
  Globals gGlobals;
  } // namespace module
  

  • Put restricted-use or limited-scope globals in "RESTRICT" namespace ("restricted" is a C99 reserved word).
• "s" suffix for a plurality such as container
  Searchability is more important than spelling.
  Eg, write "factorys" [sic] not "factories".
• Get(), Set() methods for interface to private members or to abtract data,
  Get() should return a const whenever possible
• Never write "static" to maintain threaded-code (see Threads).

Lua Coding Style

[2008/06]

See scripts/module.txt.

Globals vs. Singletons

[2009/10]

Singletons are preferred (despite being slightly slower and cumbersome to write). A limited amount of globals are used for very-frequently-accessed globals or some singletons themselves need to access a global that is plain data.

General Information about Globals and Singletons

Singletons have two problems:

1. They won't be automatically destroyed at program exit.
2. Overuse of singletons can lead to two singletons with a circular dependence.

When multiple globals are really necessary and one global depends on another, an option is a global C++ struct. C++ defines the order of construction of members in the order they are declared (don't confuse with the order of initialization list). C++ will automatically destroy them in the reverse order at program exit.

#define GET_WINDOW() (module::gGlobals.mWindow)  // behaves as a singleton so named accordingly
#define GET_GUI()    (module::gGlobals.mGui)

namespace module {

struct Globals
{
    Window    mWindow;    // no dependencies
    Gui       mGui;       // depends on mWindow (ok)
};

#if PROGRAM_MODULE_CC
Globals globals;
#else
extern Globals globals;
#endif

} // namespace module

Reminders

[2004,2009/05]

Do

• Prefer C++ <cmath> over C <math.h> and write the std:: prefix.

C++ math functions are overloaded to the appropriate type. Eg, sin(f) needlessly promotes to a double, but std::sin(f) is automatically chooses the equivalent of C sinf(f).

• global vs. globals:

namespace global (singular)
class Globals (plural)

• Protect and indicate ownership of pointers using SafePtr template class.

SafePtr prevents deleting the pointed-to object.

class Object
{
    Shape*         GetShape( void );
    SafePtr<Shape> GetShape( void );
};

• Avoid dangling pointers using SharedPtr template class.

Object A passes a pointer to its member to object B. But A could be destroyed before B uses the pointer. Or B could delete the passed object, then A tries to use it. SharedPtr can prevent these problems.

• Do write world coordinate constants inside the WORLD_COORD() macro in case world coordinates might scaled in the future.
• (Assuming NULL cannot be avoided) do NULLify a pointer to a deleted object. This protects against multiple deletions in case a member pointer is static (delete NULL is a NOP).
• A bug results if a loop that iterates a list calls a function that alters it.

Don't

• Don't save state across multiple frames (in an Object) unless the state is per-view (since multiple views are possible).

Last modified: Wed Feb 3 18:24:24 CST 2010