lovr-ODE/CSR.txt

CODING STYLE REQUIREMENTS

Copyright (c) 2011-2017 Oleh Derevenko
This article is provided to you under the terms of Artistic License 2.0
(http://www.opensource.org/licenses/artistic-license-2.0).

(I) General Coding Requirements
=============================================================================

1. Not more than one complex construction per function
----------------------------------------------------------------------------

A function must not contain more than one* operator from the following set:
for, while, do..while, switch and constructions try..catch, try..finally. 
Moreover, those operators/constructions must not appear inside of a 
conditional operator.

* Loop inclusion is allowed if multi-dimensional array must be iterated and 
all the elements are uniform and need to be processed linearly.
try..finally construction inclusion is allowed for several resource 
allocations that need to be performed together.


2. Absence of jumps
----------------------------------------------------------------------------

goto and continue operators must not be used.


3. Single exit point at the end of function
----------------------------------------------------------------------------

A function must not have other exit points except for the end of its 
definition. If a function returns a value, return operator must be the last
syntactical construction in the function.


4. Zero value means failure
----------------------------------------------------------------------------

Function results must be chosen the way that binary zero value had a meaning
of failure. Similarly, types must be designed so that binary zero element 
had the meaning of an invalid value (if invalid element concept is applicable
for the type).


5. Variables and parameters are initialized with zeroes
----------------------------------------------------------------------------

Variables and class fields must be initialized with values of binary zero 
presentation. Public enumerated types must be designed to have zero element 
and that element is to be the default element. Function default parameters 
must be chosen in the form to have binary zero value.


6. Variables are not reused
----------------------------------------------------------------------------

Variables must not be reused for other purposes after they have already been
used for something. The only value that might be stored in a variable is that
described with its name.


7. Parameters passed by value are treated as constants
----------------------------------------------------------------------------

Parameters that are passed by value must not be modified*. All of them must
be treated as if they have been implicitly declared with const modifier.

* An exception could be the case when a value loses its meaning (e.g. a 
pointer to an object being deleted).


8. Result assignment is performed at the end of function
----------------------------------------------------------------------------

Every function returning a result must have a variable to contain the result
of that function. It is to be declared (initialized if necessary) at the 
beginning of the function* and the only access to it after that should be its
final value assignment. The assignment should be the last meaningful operator
in an execution branch**. Several assignments, one per each execution branch,
are allowed.

* It is allowed to declare result variable with assignment immediately before
return operator.
** It is allowed to include technical constructions like logging or 
performance measuring after result variable assignment.


9. Parameters by reference are not used in expressions
----------------------------------------------------------------------------

Parameters of simple types passed by reference must be copied into local 
variables at function entry and then be assigned their final values at 
function exit.
Output parameters can be initialized at function entry and must be assigned
their final values immediately before the function result variable assignment.


(II) Class Design Requirements
=============================================================================

1. Classes work with their fields on their own
----------------------------------------------------------------------------

A function or method must not call several methods of other class, some of
them being used to return and the others being used to assign the class fields.
Such a code must be implemented as a method of that other class.


2. No direct access to the fields
----------------------------------------------------------------------------

All the work with class fields (including fields of own class) must be 
performed with aid of dedicated methods (accessors) that return and assign 
field values. Exceptions can be made for constructors/destructors and methods
dedicated for field initialization/finalization.


3. Private fields only
----------------------------------------------------------------------------

All class fields must be private.


4. No code in constructors and destructors
----------------------------------------------------------------------------

Class constructors must not have raw code other than doing trivial field 
initialization. If creation of contained objects is necessary or other 
operations need to be done they are to be performed via calls to the class 
methods rather than placed directly in constructor. Initial zero-assignment
to a field is always required even if that field is later to be 
unconditionally assigned in methods called from the constructor.
Similarly, a destructor must free contained objects with calls to the class 
methods rather than containing that code inline.


5. No code in callbacks
----------------------------------------------------------------------------

Event handlers, callback interface methods and static callback methods must 
not have meaningful code within them. Their implementation should validate 
input arguments, convert them to proper internal types if necessary, and call 
one or more other methods of the class. These methods must not be declated in
public section.


6. No public virtual methods
----------------------------------------------------------------------------

Methods declared as virtual must not be public. The public calls to such 
methods must be wrapped with ordinary class methods.


7. No logical level violations
----------------------------------------------------------------------------

Methods of lower logical levels must not call any methods of higher logical 
levels of the class. In particular, methods declared as protected and private
must not call methods declared in public sections of own or ancestor classes.
Methods declared as public may only call protected and private methods.
Similarly classes of lower logical levels must not call public methods of 
classes at higher logical levels. Such calls are only possible via dedicated 
callback methods or callback interfaces.


(III) Canonical Function Structures
=============================================================================

0. Preamble
----------------------------------------------------------------------------

Following are general function structures encouraged to be used for coding 
all the program logic. Any algorithm with branching can be implemented
with these types of functions.

Using these function structures helps to make code clear and error-proof.


1. A Boolean Function
----------------------------------------------------------------------------

The Boolean Function can be used to implement algorithms with conditional 
branching.

bool PerformSomeAction(...)
{
    bool bResult = false;

    // Some linear code

    if (...)
    {
        // Some linear code

        if (...) // Optionally...
        {
            bResult = true;
        }
    }
    // Optionally...
    else if (...)
    {
        // Some linear code
        
        bResult = true;
    }

    return bResult;
}

The idea is to have result variable initialized with false at entry and then 
have an arbitrary structure of conditional operators with some branches 
changing result variable to true on exit.


2. A Validation Function
----------------------------------------------------------------------------

The Validation Function is an alternative to Boolean Function to implement 
conditional logic. It's mostly convenient for implementing multi-step 
algorithms that may fail (like validations or initializations of multiple 
items of non-uniform nature).

bool PerformSomeValidation(...)
{
    bool bResult = false;

    do
    {
        // Some linear code

        // Optionally...
        if ( !(...) )
        {
            // Some error handling // Optionally...
            break;
        }

        // Optionally...
        if (...)
        {
            // Some linear code

            if ( !(...) )
            {
                // Some error handling // Optionally...
                break;
            }

            // Some linear code
        }

        bResult = true;
    }
    while (false);

    return bResult;
}

If function execution has side effects which need to be rolled back in case 
of failures on subsequent steps the function structure can be altered to the
following form.

bool PerformSomeInitialization(...)
{
    bool bResult = false;

    bool bFirstSideEffectApplied = false, bSecondSideEffectApplied = false, ...;

    do
    {
        // Some linear code

        if ( !ExecuteFirstSideEffectApplication(...) )
        {
            // Some error handling // Optionally...
            break;
        }

        bFirstSideEffectApplied = true

        // Some linear code

        if ( !ExecuteSecondSideEffectApplication(...) )
        {
            // Some error handling // Optionally...
            break;
        }

        bSecondSideEffectApplied = true

        ...

        // Some linear code

        if ( !ExecuteLastSideEffectApplication(...) )
        {
            // Some error handling // Optionally...
            break;
        }

        bResult = true;
    }
    while (false);

    if (!bResult)
    {
        if (bFirstSideEffectApplied)
        {
            if (bSecondSideEffectApplied)
            {
                if (...)
                {
                    ...
                }

                ExecuteSecondSideEffectRollback(...);
            }

            ExecuteFirstSideEffectRollback(...);
        }
    }

    return bResult;
}


3. A Loop Validation Function
----------------------------------------------------------------------------

The Loop Validation Function can be used for processing sequences of items 
while the processing of each or some individual items can fail.

bool PerformLoopValidation(...)
{
    bool bAnyFailure = false;

    for (...) // Or any other loop control operator
    {
        // Some linear code

        if ( !(...) )
        {
            // Some error handling // Optional
            bAnyFailure = true;
            break;
        }

        // Some linear code
    }

    bool bResult = !bAnyFailure;
    return bResult;
}

In case if a loop processing function may apply side effects on each step 
which need to be reverted in case of a failure on subsequent steps the 
functions need to be organized in the following four-function two-level 
structure.

bool PerformLoopInitialization(...)
{
    bool bResult = false;

    size_t nFailureItem;

    if (DoPerformLoopInitialization(..., nFailureItem))
    {
        bResult = true;
    }
    else
    {
        DoPerformLoopFinalization(..., nFailureItem);
    }

    return bResult;
}

void PerformLoopFinalization(...)
{
    DoPerformLoopFinalization(..., npos); // Here "npos" stands for the invalid item index
}

bool DoPerformLoopInitialization(..., size_t &nOutFailureItem)
{
    bool bAnyFailure = false;
    size_t nOutFailureItem = npos;

    for (...) // Or any other loop control operator
    {
        // Some linear code

        if ( !(...) )
        {
            // Some error handling // Optional
            nOutFailureItem = ...;
            bAnyFailure = true;
            break;
        }

        // Some linear code
    }

    bool bResult = !bAnyFailure;
    return bResult;
}

void DoPerformLoopFinalization(..., size_t nExternalFinalizationEndItem/*=npos*/)
{
    size_t nFinalizationEndItem = nExternalFinalizationEndItem == npos 
        ? ... /* total item count */
        : nExternalFinalizationEndItem;

    for (... /* loop until nFinalizationEndItem */) // Or any other loop control operator
    {
        // Some linear code
        RevertLoopItemSideEffects(...);
    }
}