Guideline: Naming Conventions |
This guidance provides recommendations for naming conventions for models and source code.
Relationships
Related Elements | Platform Independent Model Analysis Collaboration Platform Specific Model Design Collaboration Scenario Source Code Model Software Design Discipline
Main Description
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. Identifier names longer than 16 characters are difficult to read 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 Attributes and variables should append standard abbreviations for units to their names when they apply (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 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()
IBM® Rational® Harmony™ for Embedded RealTime Development Base Concepts Plug-in Copyright