diff options
Diffstat (limited to 'libs/ode-0.16.1/CSR.txt')
| -rw-r--r-- | libs/ode-0.16.1/CSR.txt | 422 |
1 files changed, 422 insertions, 0 deletions
diff --git a/libs/ode-0.16.1/CSR.txt b/libs/ode-0.16.1/CSR.txt new file mode 100644 index 0000000..7d4ca2e --- /dev/null +++ b/libs/ode-0.16.1/CSR.txt @@ -0,0 +1,422 @@ +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(...);
+ }
+}
+
|