Developer's guide

For cite-effect, version 1.3


//+++to do
//---to deprecate
//???to investigate
//patch[01](temporary?) bug fix number 01
//!!!to remove before releasing (development only)

Logical view

Database design

Flat file is used instead of indexed database since sequential access is only necessary.

Split symbols/references files is used instead of merged files since resolving symbol ambiguity will take place before graph processing, and does not need the list of references.

Relevent referer-relationships (parser-dependent) :

Graph algorithms

To find homes of a referee: (the deepest node in each graph where all references occur, directly or indirectly)
  1. select all parents of referee, starting from the graph roots, recursively, in direct line (do not walk loops); quit if empty
  2. do recursively and once on each node, down the parents' tree:
  3. replace each root by deepest home node= first in .homes_ list
  4. remove duplicate in updated list of graph roots
  5. add parents of referee, starting from the graph roots, recursively, this time walking loops

//+++ abortable parser

returns Id_ of token at given fpos
lexer returns ABORT token
parser detects 'expr ABORT' and ignores syntax error

//+++ IDE integration

max path/filename length used in output layout.

Coding style

Use 2-space indentation.
Have your editor place 2 hard-coded space characters instead of a tab character in source files.

Have each .cpp file refer to its .h file, and .h file refer to this .html file (pointing to the UML diagram).


To help refactoring, avoid natural language names for symbols. For example, use 'Parser_' rather than 'Parser', so that global name change will not affect occurence of 'Parser' in comments

Object deallocation

Use foo( Object param&) instead of foo( Object param*) when foo becomes responsible for deallocating the supplied object.

Use 'virtual prune_()' to allow virtual destructor code (C++ does not allow overriding destructor method).

Class documentation (optional)

To describe normal usage of a class and its objects, write in the header file '.h' the grammar rules for the valid sequences of method invocation. See for example common_.h.

Write the grammar using the Backus-Naur form (BNF) syntax. It can be extended with the following syntax :