Skip to content

Modeling

This section concentrates on best practices for modeling that do not depend on the modeling tool you use. Where there are modeling tool specifics, the name or category of the modeling tool is mentioned in the text.

Naming

Model element names

Use short names for you model elements, but not too short. Always take into account, whether someone else who reads the name of a model element can easily grasp what it is used for. When you for instance give a name CompleteProcess to a user interface view, it is pretty short, but you do not know what process it is good for. Also: Somebody else might choose the same name for a different process. It would be better to use a name like CompletePurchaseProcess.

Namespaces

If your modeling language supports the concept of namespaces, use them wisely. Let model elements that belong to the same functional requirement share the same namespace. When your model gets bigger, be sure to not use one and the same namespace for everything. And don’t use technical terms in modeled namespaces. A namespace like com.generative‑software.dataaccess or com.generative‑software.databasetable for instance is not an optimal choice. Very short namespaces like sales can make sense, but only when a generator is capable of “completing” the namespace in the generated code by prefixing it with a common namespace like com.generative-software.erp. When generating Java code, the resulting Java package name then would be com.generative-software.erp.sales. Please note that generators might append technical terms to package names. So there might be generated Java packages like com.generative-software.erp.sales.webservice or com.generative-software.erp.sales.entity.

Uppercase or lowercase?

Normally, it is not necessary to invent a rule to always start model element names with an uppercase or a lowercase letter. Generators should change the case of a name’s first letter to adapt it to the conventions of the targeted programming language.

Modularization

Make sure your model is not becoming a big ball of mud. When you are modeling by writing to files, make sure the files are not laying around but are organized within subdirectories. As a rule of thumb, you should put all files that share the same namespace in one and the same directory (that directory could still have subdirectories).

When modeling with files, a file often has the meaning of a module, holding things that belong together and can be re-used. Choose a file name that tells a user what can be found inside. A file wherein a user interface for a sales program is modeled, should not have a name like userinterface.gapp. The name SalesUi.gapp or UiSales.gapp would be better.

Modeling tools that are not file based normally ship with a proprietary mechanism for modularization. But the rules for naming and organizing modules are still the same.