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.

Naming Conventions¶

It makes sense to define conventions for the naming of model elements. It helps to keep the orientation in bigger models. Also, after code generation, it makes handling the source code files easier. The following table gives you an example for such conventions for various DSLs:

DSL Persistence¶

Element Type and potential Option Value	Pattern for the Name	Convention
`entity` `Abstract = true`	Abstract[name]
`field` `Id = true`	pk	pk is the short form of “Primary Key”. Every data field or parameter name that holds a primary key has “pk” in its name, e.g. “pkPurchase” or “purchasePk”.

DSL Function¶

Element Type and potential Option Value	Pattern for the Name	Convention
`interface`	[name]Service	e.g. PurchaseService
`implementation`	[name]ServiceImpl	e.g. PurchaseServiceImpl
`client`	[name]ServiceClient	e.g. PurchaseServiceClient
`businesslogic`	[name]BusinessLogic	e.g. PurchaseBusinessLogic
`function`	[name]	It is not recommended to use a postfix here.

DSL UI¶

Element Type and potential Option Value	Pattern for the Name	Convention
`view`	[name]View
`display` `type = List`	[name]List
`display` `type = Form`	[name]Editor	When the form is used as the `Display` for a `component` of type “EmbeddedComponentGroup”, it might be necessary to use a different term than “Editor”, e.g. “Actions” for a set of `buttons` that are contained in a `display`.
`display` `type = Grid`	[name]Grid
`display` `type = Tree`	[name]Tree
`display` `type = TreeTable`	[name]TreeTable
`layout` `type = Tab`	[name]Tab
`layout` `type = Wizard`	[name]Wizard
`layout` `type = Split`	[name]Layout
`toolbar`	[name]	The toolbar’s name should start with the name of the `layout` or the `display` that it is going to be assigned to and end with “Toolbar”, e.g. PurchasesListToolbar.
`button`	[name]	The button should simply tell the action it is going to perform, e.g. SaveButton for a save button. Appending “Button” makes it then easier to search for the related code fragments. Ensure that you always use the same verb for one of the action purposes (modeling option `ActionPurpose`). Example: Always use AddButton for buttons with `ActionPurpose = Add` instead of AddButton, CreateButton, NewButton. In more complex views it helps to append the name of the “thing” the action is related to, e.g. SavePurchaseButton.
`button` `NavigationTarget = [view name]`	[name]	e.g. Open[view name]Button for a button that opens a details page.
`link` `NavigationTarget = [view name]`	[name]	e.g. Open[view name]Link for a link that opens a details page.
`type` for Link Option `InitParameters`	[view name]InitParams
`component` component type “Choice”	[name]Choice	e.g. a component to choose a language: LanguageChoice
`component` component type “Image”	[name]Image	e.g. a component to display a product image: ProductImage. If the image more serves the purpose of an icon, you can use the term “Icon” instead of “Image”.
`component` component type “Label”	[name]Label	e.g. a component to display a street name: StreetLabel
`component` component type “TextField” or “TextArea”	[name]Input	e.g. a component to enter a price: PriceInput
`component` component type “Chart”	[name]Chart	e.g. a component to show a revenue chart: RevenueChart
`component` component type “BooleanChoice”	[name]Check	e.g. a component to register for a newsletter: NewsletterCheck
`component` component type “DateSelector”	[name]	The name of the purpose of the data typically already tells something about the used component, e.g. a component to enter a birthday: Birthday. If the date is meant to be read-only, a “Label” can be used and the component’s name is BirthdayLabel.
`component` component type “FileUpload”	[name]Upload	e.g. a component to upload an invoice: InvoiceUpload.
`component` component type “HTML”	[name]RichText	e.g. a component to enter a complex product description: ProductRichText.
`component` component type “Map”	[name]Map	e.g. a component to display a map that shows stores: StoreLocationMap.
`component` component type “Range”	[name]Range	e.g. a component to enter the number of purchased items: NumberOfItemsRange
`component` component type “Timeline”	[name]Timeline	e.g. a component to manage trips of a taxi service: TripsTimeline.
`component` component type “Tree”	[name]Tree	e.g. a component to manage an organization’s management hierarchy: ManagementTree.
`component` component type “Video”	[name]View	e.g. a component to display a product video: ProductVideo.
`component` component type “EmbeddedComponentGroup”	[name]	e.g. a component to display a set of buttons: Actions, which is a typical pattern in `displays` of type `List`.

DSL Product¶

Element Type and potential Option Value	Pattern for the Name	Convention
`capability`	[name]Capability
`product`	[name]	It is not recommended to apply a pre- or postfix here.
`feature`	[name]	It is not recommended to apply a pre- or postfix here.
`application-ui`	[name]UiApp
`application-service`	[name]ServiceApp

DSL Test¶

Element Type and potential Option Value	Pattern for the Name	Convention
`test`	[name]Test	e.g. ProductSearchTest. When a certain `businesslogic` or `view` is going to be tested, it makes sense to prefix the word “Test” with the name of the related model element.
`step`	[name]	It is not recommended to apply a pre- or postfix here. A step’s name should simply tell us what it is doing/testing. If a modeled `test` is small enough and gives a relatively narrow context, you can, for the sake of simplicity, number the steps serially: Step1, Step2, Step3.

DSL DES (Deeply Embedded Systems)¶

Element Type and potential Option Value	Pattern for the Name	Convention
`Application`	[name]_App
`Task`	[name]_Task
`RTOS`	[name]	It is not recommended to apply a pre- or postfix here. Example: Free RTOS
`Hardware Trigger`	[name]_HWTrigger
`Software Trigger`	[name]_SWTrigger
`Input Port`	[task name]_In	A task has exactly one input port. Thus, the name of the input port can always include the name of the task.
`Output Port`	[task name]_[name]_Out	A task can have several output ports. The name of the output port includes the name of the owning task as well as the name of the purpose of the outgoing data.
`Actuator` `Sensor` `Device`	[name]	It is not necessary to apply a pre- or postfix here. Often, the name of the hardware is exactly the name of the physical product of hardware manufacturers. If the model is intended to be independent of manufacturers, the hardware can be given names that exress what they are doing or measuring, e.g. Humidity for a humidity sensor.
`Hardware Connection`	[name]_Con
`Hardware Function`	[name]	It is not recommended to apply a pre- or postfix here. The function name speaks for itself.
`In Parameter`	[name]_ParamIn
`Out Parameter`	[name]_ParamOut

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.