Skip to main content

Naming Conventions

When building NS application models, it is important to stay consistent and follow naming standards as closely as possible. The content of the models is used to generate all sorts of artifacts, which means that a dependable naming scheme is an excellent help to produce clean and consistent results.

As a general rule, we try to use the English language in all models. As English is a language that is used very commonly in many industries, this makes the models considerably more accessible. It also reduces the need of finding translations for technical terms that often originated in English.

caution

Avoid using names such as common terms that are frequently used as "reserved words" in programming languages, such as (but not limited to) case, export, function, id, import, interface, name, long, package, parameter, string, var.

Element naming rules​

  • Application/ApplicationInstance element:
    • A relevant name for the application in camelCase.
  • Component element:
    • A unique name in camelCase to facilitate the exchange of components.
    • The name of a component should describe the specific concern it encapsulates, rather than being generic.
  • DataElement element:
    • The name of a DataElement should always be a singular noun in PascalCase, that is unique within its component.
    • Ideally the name of a DataElement is anthropomorphic (describing a real life concept).
    • Avoid using words such as Data, Info or Details in the name of a DataElement, as these are used as suffixes for many classes generated in the JEE Application Stack.
  • Field element:
    • The name of a Field should always be a singular noun in camelCase, that is unique within its component.
    • Avoid reusing the name of the DataElement in one of its fields.
      Anti-Pattern Example

      Dog.dogName would be a bad field name, as the dog in dogName is redundant if the name of the DataElement is already Dog. The context of the Field as part of the DataElement implies that the name is the name of a Dog.

  • Finder element:
    • The name of a finder should always start with findBy, except for findAll and custom finders.
    • Finder operator pairs (field name + operation) in the name of a finder should always be written in PascalCase. When multiple finder operator pairs are used, they should be separated with an underscore in the name.
      Example
      • A finder used to search by the field name with operator Eq: findByNameEq
      • A finder used to search by the field code with operator Se and invoicedAmount with operator Gt: findByCodeSe_InvoicedAmountGt
  • TaskElement element:
    • The name of a TaskElement should be a singular noun in PascalCase.
    • The name should be a noun derived from a verb. It should describe the action being performed by the task.
      Example
      • A task which sends an email could be named SendEmail. The name is derived from the verb "to send".
      • A task which reports errors to a server could be named ErrorReporter. The name is derived from the verb "to report".
  • FlowElement element:
    • The name of a FlowElement should be a singular noun in PascalCase.
    • A common practice is to use the suffix "Flow" in the name for clarity, though it is redundant given that it is an instance of FlowElement.
  • DataCommand element:
    • The name of a DataCommand should be a singular noun in PascalCase.
    • It is bad practice to suffix the name with "Command".
      Anti-Pattern Example

      A command to set the enabled state of an element should not be called SetEnabledStateCommand. In the JEE Application stack, every DataCommand of a DataElement is implemented as a nested class of <DataElement>Command. As such, the resulting class would be <DataElement>Command.SetEnabledStateCommand, which clearly shows that Command in the name of the DataCommand isredundant.

  • DataState element:
    • The name of a state depends on the type of state:
      • A begin- or endstate should be a singular noun that indicates the current state of the DataElement it applies to.
        Example

        A newly created instance of a DataElement could have the beginstate Initial, whereas after being processed by a task, it could be assigned the endstate Registered.

      • An intermittent state of a DataElement should be a name derived from a verb that describes the action being performed.
        Example

        A DataElement that is being processed, going from states Initial to Registered, could have an intermittent state Registering.

      • A failed state of a DataElement that occurs when a task failed to perform an operation, should be named after the action and have the suffix "Failed".
        Example

        A DataElement that is being processed, going from states Initial to Registered, could be set to the failed state RegisterationFailed if a task fails.