# 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