Naming conventions provide consistency within a document or model lessening the burden on the developer reviewing it.
Naming conventions apply to any element that can be named, but this guidance focuses on developer work products and
elements.
General
-
Use naming meaningful in the context of the usage
-
An exception is temporary variables that might be used in a local scope, such as looping variables
-
Avoid overly long names. It is difficult to read identifier names longer than 16 characters
-
Avoid the use of acronyms in an identifier unless the acronym is in a project-approved acronym list
-
An exception might be standard abbreviations for units for scalar variables appended to the identifier name
(e.g. pressure_psi)
-
When a phrase is used for an identifier name, you may use one of two mixed-case styles (this decision should be
project wide),
-
Remove white space to make the name into an identifier but make the beginning of each new word uppercase
(except for the first word (see naming of classes and class features), such as digitalMotorController
-
Replace white space with an underscore character, such as digital_motor_controller
-
Even in a case-sensitive language, never use case to distinguish names (e.g. sourceFile and Sourcefile).
Files
-
File names should not have white space unless you are sure that all operating systems and tools that may
ever use the files allow it.
-
Filename should reflect their content
-
Files should be divided into an interface (header) file and an implementation file.
-
The header file should only contain declarations, not implementation. It should declare all elements with
public visibility
-
The implementation file should contain the elements that implement the declarations in the header file plus
any needed protected or private elements
Diagrams
Diagrams should be named according to their usage or content. Since each diagram should have a mission statement, the
mission can be exposed within the name (e.g. scenario1_targetAcquired for a sequence diagram, acquireTargetCollaboration
for a class diagram realizing a use case "Acquire Target", flowControlAlgorithm for an activity diagram, NavigationUseCases
for a use case diagram containing use cases and actors focusing on navigation, etc).
Classes
-
Class names should be meaningful singular nouns or noun phrases (e.g. ECGMeasurement)
-
Class names should begin with an uppercase letter and may have letters, digits or "_"
Class Features
A class feature is a sub-element within a class, such as a port, attribute, or operation.
-
A class feature should begin with a lower case letter.
Attributes and Variables
-
Attributes and variables should be scoped within an enclosing namespace to prevent name pollution
-
Attributes and variables should have meaningful singular noun or noun phrase names (e.g. speed_rpm)
-
Attributes and variables are class features and so class feature conventions apply
-
When applicable, attributes and variables should append standard abbreviations for units to their names (e.g.
speed_mph)
Operations, Functions and Messages
-
Operations, functions, and messages should be scoped within an enclosing namespace to prevent name pollution
-
Operations, functions, and messages should have meaningful verb or verb phrase names (e.g.
computeAngleInRadians)
-
Operations, functions, and messages are class features and so class feature conventions apply
-
Operations and functions should append standard abbreviations to their names for units when they apply
(e.g. speed_mph)
Types
Types identifies should be named beginning with an upper case letter
Type names should be meaningful noun or noun phrases (e.g. RadarReturnCode)
Use Cases
-
Use cases should begin with an upper case letter
-
Use cases define functionality, and so meaningful verb or verb phrases should be used for names
-
An exception is when a use case refers to an operational mode (usually such a use case specializes another)
(e.g. AutoGuidanceMode specializing NavigateSystem use case.
-
Use cases may, optionally, contain white space if that option is supported in the selected modeling tool
States
-
States are a condition and so should have meaningful verb or verb phrase names (e.g. WaitingForUser or
RotatingTheAntenna).
-
State names should reflect the condition of the instance for which they define the behavior
Transitions and Events
-
Transitions are named by the events that trigger them
-
Events are occurrences and therefore singular nouns
-
Event names should be meaningful noun or noun phrases, optionally prefaced with 'ev' (e.g. evButtonPush)
-
An exception is when the triggering event is a timeout; in this case, use tm() or after()
|