Palomino - Coding

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

Contents

• Main Contents

• 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.
• Globals:
  • Put widely-accessible globals as members of a Global class. Instantiate it as "Global global;".
  • Put restricted-use globals in "restrict" namespace.

  Restricted globals are typically independent variables with a narrow scope. namespace is spelled "restrict" as "restricted" is a C99 keyword.

• "s" suffix for a plurality such as container
  Searchability is more important than spelling.
  Eg, write "factorys" [sic] not "factories".
• "cnt" for a count or anything that is incremented
  (rather than the ambiguous "s" suffix: eg does "polygons" mean an array or a count?)
• 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

[2007/06]

Globals are either defined as members of a Global class in each library, or as Singletons. Both have advantages and disadvantages.

As members of a Global class, globals become obvious and are easy to search. They're accessed by writing "global.mMember". The order of construction is the order they're declared in the class. And, they auto-destruct in inverse order at program exit. A disadvantage is that this order is limited to the scope of the class.

Singletons solve the problem of globals (or static objects) depending on other globals. Disadvantages are that Singletons don't auto-destruct as Global members do, and Singletons are difficult to find when searching for globals (for the purpose of implementing threading).

global::mWorld.GetEdge();  // obvious global
World::GetEdge();          // hidden global

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: Tue May 26 21:43:18 CDT 2009