Guidelines

Coding guidelines

---

The GUIDOEngine architecture

The graphic representation of a score goes thru the transformation of an abstract representation of the score (AR) to a graphic representation (GR). The AR level is similar to the Guido Music Notation language and may be viewed as the memory representation of the textual score description. The transformation steps are the following:

1. AR to AR tranformations: applies logical layout tranformations e.g. computes stems direction, beaming, barlines, etc.
2. AR to GR tranformations: instantiates the AR representation in the graphic space: computes the elements graphic position, line spacing, line breaking, etc.

For more details about the architecture and algorithms, you should refer to Kai Renz dissertation.

The library source code is located in the src/engine folder. The abstract folder contains the code related to the AR representation, the graphic folder contains the code related to the GR representation.

Graphic rendering

Graphic rendering operates using an abstract VGDevice layer. Any platform specific renderer must implement a native VGDevice. Native graphic devices are available for MacOS (using Quartz), Windows (using GDI or GDIPlus) and Linux (using Cairo). Additionnaly, environments like Qt, OpenFramework, OpenGl, Juce provide also an implementation of the VGDevice interface. The corresponding code is located in:

• src/engine/include: the abstract VGDevice description
• src/engine/devices: the platform independent devices
• platforms/macos|linux|win32: the platform specific devices
• environments: the Qt, OpenFramework, OpenGl and Juce implementations

Coding rules

The current code base inherits from years of development and most of the algorithms have been designed before the advent of C++ and standard libraries. Thus, it doesn't generally follows the rules below, which doesn't prevent to improve it in this direction.

• class names: use the upper camel case convention
• method names: use the lower camel case convention
• fields names: must start with f and use next the camel case convention
• constants: must start with k and use next the camel case convention

Recommendations

• Expose class fields and methods only when necessary. The public section of a class should reflect it's services only and not it's internal implementation. The protected section should reflect behaviors shared at inheritance level only. And otherwise, make everything private as much as possible.
• Don't use the friend attribute
• Use and abuse of the const keyword whenever possible.

Validation

The validation process is intended to verify that a modified library doesn't introduce undesired changes. The underlying idea is that the library output should remain the same from one version to another one. Of course and when correcting bugs or improving the graphic layout, changes may occur but must be carefully checked.

Validation tools are located in the validate folder. You must start to generate a set of reference files BEFORE making any change to the library:

> cd validate
> make

Output files are generated in a folder carrying the current version as name (e.g. 1.6.4.0). The version number if taken from the guidoversion.txt file that you can freely modify.

To validate a set of changes you must:

1. change the version number in guidoversion.txt
2. run make to generate new output files
3. compare with the reference files:
   > make validate VERSION=x.x.x.x
   (where x.x.x.x is your reference folder name, e.g. 1.6.4.0).
4. check any difference that you get on output.

Note for Windows

Validation is based on the 64 bits version of the library and tools. To copy the tools at the appropriate location, you must run

> make win64

from the validate folder each time you make changes to the library or tools.