Goanna Design Principles

This page attempts to document a lot of the design principles used in Goanna, to help people with understanding the code base and extending it.

Software Design

Goanna uses an object oriented design which attempts to be relatively clean and cohesive. Several principles govern its design.

Principle of Least Knowledge

Note: There is a formal Principle of Least Knowledge, also called the Law of Demeter. It is a more extreme version of this principle. We aren't that strict.

Basically, the Principle of Least Knowledge means that an element (module, class, etc.) A should know no more about B than it needs to in order to accomplish its purpose.

One-way Interactions

Interactions between modules in particular, and also classes where appropriate, should be as one-way as is practical. E.g., the Goanna UI knows how to manipulate the object model, but the object model knows nothing of the UI, and cannot directly call things in the UI. Where it is required to call in the reverse direction of some interaction, the preferred mechanism is signals (callbacks).

Example: The UI can manipulate a model object. However, if the model object wants to be able to call in to the UI, or manipulate it in some way, it should provide a signal encapsulating the desired behavior (e.g., "notify of change"). The UI can then connect to this signal with the method it wants to use to watch for the event. This keeps the interaction one-way - the model can notify any interested party of a change, and the UI connects to that and also makes changes.

The one-way interaction principle makes code logic easier to develop and follow. Signals can still make things hairy, but it's better than it might otherwise be.

Const Correctness

C++'s const mechanism provides a powerful way to ensure and enforce read-only-ness of objects in certain contexts. Goanna attempts to utilize that, particularly in the object model. Const isn't really used in the UI code itself, as it makes little sense there.

The following rules guide the usage of const in the Goanna:

1. If something can be const, it should be (e.g., any method which doesn't modify an object should be const if possible and if doing so doesn't violate other goals). This really only applies in the implementation of the model and topographay; const isn't used much in the UI code.
2. The view of the entire model as seen through a const object is read-only. You cannot obtain a mutable system from a const node, for example. This means that accessors which return lists of children, parents, etc. need to be const-overloaded. The non-const version can return a plain pointer (usually a RefPtr), and the const version must return a pointer-to-const (frequently a WeakPtr).
3. Don't cast around const. There is one place, in the electrostatic positioning code, where const is cast away, and this code needs to be reviewed and hopefully fixed. This rule applies in general to all C++ code.

UI Design

Most of the UI design principles are encapsulated in the GNOME Human Interface Guidelines. Follow them as appropriate.