The VISH API

See also:

Coding Style and Hints

VISH Design Issues

Interfacing the Standard Template Library

No header file must include any STL header. Internally, STL may be used, but in particular as MS VC 6 produces crashing code when using STL iterators across DLL boundaries, it must not be exposed to the API. Consequently, all STL usage is hidden. This choice affects the Iterators.

Void Pointers

Void pointers are deprecated and to be avoided. Instead, all operations on unknown types need to be casted into a system of abstract classes with virtual functions operating on concrete types. The implicit dynamic casting of MemCores RefPtr template is helpful here.

Naming Convention

To allow reading the code similar to human language, procedures which perform real actions are associated with verbs and written in lower case. Data objects are associated with substantives and written capitalized. Procedures, which do not perform significant actions but e.g. just refer to an object procedurally, are considered as substantives as well and thus also written capitalized.

Procedures and objects should be named with the shortest possible full human word describing its purpose. It shall be concise and descriptive such that commenting its purpose becomes superfluous. Consecutive names are allowed, but should be used only if an object or procedure operates one more than object that is already defined in the library. Basic objects which do not refer to others shall be single-worded.

Abstract classes end with a trailing "Base". Types (in particular typedefs) are named with a trailing "_t", similar to STL.

For pragmatic reasons, this naming convention might not always be used consistently. This naming convention is thus not to be considered as strictly enforced, but as guide rule. Still, any deviations might be considered as a bug and adjusting such places is recommendable to increase readability.

Lifetime of variables

Definition of local variables shall be such that their lifetime is as shortest as possible. For instance, loop variables shall be valid only within the loop, and variables used in an if-block shall be defined in the if-condition itself, when possible, as in:

 if (bool ok = valid() )
 {
   ...
 }

but not

 bool ok;
 if ok = valid() )
 {
   ...
 }

In general, variables shall not be defined before they are actually used, and any variable must be initialized at the point of its definition.

Static Variables

Static variables are problematic and should be avoided, but they still serve their purpose for many cases. To reduce the hassle of undefined initialization time, static variables should not be defined directly but merely be accessed through a function. I.e. code such as

static Class Object;

is deprecated and needs to be replaced by the simple variant

static Class&Object()
{
static Class myObject;
        return myObject;
}

Here, all usage of the static object just requires additional parenthesis, but the huge benefit is the clearly defined initialization time of the static object upon the first usage of the object, whereas in the unprotected first variant the object might be initialized before main() or during loading of a shared library when some essential components used by the object have not yet been initialized. By virtue of procedural access to static objects, a proper initialization chain is ensured.