UML notation

Snorky uses certain idioms and conventions in its design documents, the purpose of this section is to explain those.

Types

Both Python and Javascript are dynamic languages which do not require type interfaces: each method can accept any kind of objects as arguments and can return anything or nothing in each call. This is exploited heavily in testing.

Anyway, for documentation, design and regular use it is important to know with certainty what kind of objects a call may accept or return, so all the design diagrams of Snorky are strongly typed.

The type names used are inspired by the Python language:

  • str: A character string. May contain Unicode characters.
  • bytes: A byte string. May not be encoded text.
  • object: Anything.
  • void: Used as a function return type, the function does not return nothing.

Some types are templates, using caret notation.

  • list<Type>: A list (array in JS) of elements of class Type.
  • dict<Key, Value>: A dictionary (associative list) type whose keys are of class Key and values are of class Value.
  • set<Key>: A set of elements of type Key, similar to an associative list, but without values.
  • iter<Type>: A generator or iterable object. Placed in a for loop yields an element of class Type in each iteration. List, dictionaries and sets are iterables. Python makes it easy to create custom iterable objects too.

Template annotations

Template types arguments may carry optional annotations to explain their purpose. For example, if we have a dictionary to index Subscription objects by a field of Subscription named token, we could write the following type declaration:

dict<token : str, Subscription>

Any amount of template arguments may carry annotations.

Typed relationships

UML has a simple notation to specify multiplicity of relationships. Most used multiplicity strings are:

  • 1: Each instance is associated with exactly one instance of the other class.
  • 0..1: Each instance may or may not be associated with one instance of the other class.
  • 0..*: Each instance may be associated with any number of instances of the other class.

When transforming diagrams into code, there is not much discussion about the two first multiplicity strings: they will be implemented as a reference of the other class type.

0..* is somewhat vague though. UML accepts some modifiers like {ordered} and {unique} that can avoid some of that vagueness, but not all.

A common approach would is to use the type list for 0..* relationships, or just treat it as a minor implementation detail.

In Snorky many relationships are powered by (sometimes several!) dictionaries in order to make searches as fast as possible (often O(1)). This is not an implementation detail, but a very important design matter: performance is all about data structures more than any other thing.

In order to fully express relationships between classes Snorky annotates them with types, using the notation explained above.

For instance, in the following example the hypothetical class ServiceManager is associated with a set of services, indexed by a field name of type str with a dictionary.

A typed relationship.

A relationship may be of any type as long as it can be used somehow to refer to an instance of the related class. In the following example the class ClientMessage has a relationship with Service over a str field. Although it has not an explicit reference to a Service instance, it can get one easily passing the service_name value to its collaborator, ServiceManager.

A less obvious typed relationship.

Color code

The color of a class has a meaning:

  • Blue: The class is not implemented yet as code.
  • Yellow: The class has been implemented.
  • Green: This class represents one defined in an external framework. The real class may have more methods or properties. Only those used in the project will be featured in the green class.

Snorky implementing a Tornado WebSocketHandler.

Properties instead of attributes

Non-strict visibility

Table Of Contents

Previous topic

Methodology of development

Next topic

Data Sync: Concept

This Page