Guideline: Method Element Naming Conventions
This guideline provides recommendations on how to name method elements.
Relationships
Main Description

This guidance provides general information on naming method elements.  For method element-specific naming guidance, see the attached guidance.

Abbreviations

It is a good practice is to provide a list of approved abbreviations for your project. Using a standard set of abbreviations simplifies searches for not only the method authoring team, but also for users of your published web site.

Name fields

Most method elements have two name fields:

  • The Name is always present since it is the internal name for the element.
  • The Presentation Name is present for some elements; it is the name displayed in the published web site for the element. Thus, a friendly name should be used.

General naming guidelines

In general, all method elements should following the following recommendations:

  • Name should reflect the essence of the element
  • Where an element has both a name and a Presentation Name field, try to name them consistently (though abbreviations may be used in the internal name)
  • Abbreviations should be either very common to the plug-in domain (for example, J2EE for Java 2 Enterprise Edition) or they should be taken out of a list of common abbreviations for the project. If abbreviations are not standardized, it is very likely that similar but not quite identical abbreviations will occur here and there, introducing confusion and errors later on

For general guidelines on naming variants, see the section on that topic later in this guideline.


Method element-specific naming guidelines

Table 1 provides element-specific guidelines for naming the different types of method elements. 

Table 1: Method Element Naming Conventions

Element Guideline Reason
Plug-in
  • use internal name for the Name field
  • use friendly name for the Presentation name field
  • Omit the word "plug-in" in the names (it is redundant)

The value of the Name field determines the directory name used in the file system.  

Compound names, separated by periods, can be used in the Name field to organize the list of plug-ins in the library view to make them easier to navigate for process authors. 

Method content package

Method content package names are displayed when viewing the method library. They are also the elements that users can choose to include or exclude from their configurations. Thus, these names need to be easy to understand and self-explanatory.

Process package

  • use friendly name for Name field (process packages only have a single name field)

Process package names are displayed when viewing the method library. They are also the elements that users can choose to include or exclude from their configurations. Thus, these names should be easy to understand and self-explanatory.

Standard category

Standard Category names are displayed when viewing the method library. They are also the elements that users can choose to include or exclude from their configurations, as well as to include or exclude from other custom categories. Thus, these names should be easy to understand and self-explanatory.

Custom category

If the custom category is to be used for a navigation view, include "view" in both name fields. 

Custom Category names are displayed when viewing the method library. They are also the elements that users can choose to include or exclude from their configurations, as well as to include or exclude from other custom categories. Thus, these names should be easy to understand and self-explanatory.

The Presentation name of a custom category that is used as a navigation view is also used as the name of the tab that is published for that view.

Configuration
  • use internal name for the Name field
  • use friendly name for the Presentation name field
  • Omit the word "configuration" in the names (it is redundant)

The Name field determines the file name used in the file system. 

Role
Task

Task names should form a verb object phrase. The verb should be carefully chosen to ensure that the action to be performed is clear to the practitioner. For a list of acceptable verbs, see the "Acceptable Verbs" table in a later section.  The object should be closely related to the output work product.

For example:  Define Test Specification
"Define" is the verb and means "to determine the essential qualities". (see Table 2). "Test Specification" is the main output work product for the task.

Alternatively, the task name may reflect the objective of performing the task, instead of being closely related to the output work product.

For example: Plan the Project.

Work product: Artifact
Work product: Deliverable
Work product: Outcome
Guidance
Capability pattern
Delivery process



Acceptable verbs

Table 2 provides a starter set of verbs. Method authors may add verbs but they should do so in such a way that avoids duplication. If a new verb is created, ensure that the definition of what it means is included in the configuration.

Table 2: Acceptable Verbs

Verb Meaning Comments
Acquire To come into possession of  
Analyze To determine the relationship of component parts  
Assemble To fit parts together Especially useful for deliverables
Assess To make a judgment of worth  
Assign To appoint to a post or duty  
Build To construct by putting parts or materials together  
Capture To document  
Categorize To analyze and group according to a particular criteria  
Cleanse To purify  
Communicate To transmit information so that it is understood  
Conduct To direct or manage  
Configure To set up for operation  
Confirm To verify that you have what's needed  
Detail To provide the details for an outlined artifact  
Develop To bring to maturity;  to provide a more specific definition  
Elicit To draw out or evoke  
Enable To make operational  
Estimate To judge approximate value  
Evaluate To determine significance or worth  
Gather To bring together into one collection  
Gather To locate and bring together  
Identify To establish identifty  
Implement To fulfill; to realize  
Initiate To facilitate the beginning  
Install To place in position of use  
Manage To direct or supervise  
Obtain To get or attain by planned action or effort  
Outline To describe key elements  
Perform To do  
Plan To describe objectives, as well as a sequence and deadline for reaching a goal; to specify how to reach a goal
Prepare To make ready  
Prioritize To set priorities  
Receive To acquire, come into possession  
Reconcile To check against another for accuracy and make them match  
Release To make available for use  
Review To examine carefully, looking for errors, omissions, ambiguity, inconsistency    
Run To perform, generally by executing a program on a computer  
Select To choose  
Specify To name or state explicitly or in detail  
Ship To trasnport an item  
Train To teach a task or job  
Understand To comprehend meaning  
Validate To confirm that a solution or process is correct  
Verify To ensure correctness according to specific criteria  


Do not use leverage because it is marketing jargon and also outdated jargon. We avoid jargon because it always becomes outdated and doesn't translate accurately.


Naming method variants

This section provides specific recommendations on how to name elements that have a variability relationship to another element.

The following table provides guidance about naming specific variants.

Element Guideline Reason
Base element
Contributor
  • use internal name for the Name field
    • use exactly the same name as the element to which the contribution is being made
    • add a suffix that identifies the plug-in providing the contribution
    • if there are multiple contributions to the same element from different packages in the same plug-in, it may also be necessary to identify the content package in the suffix
    • the suffix should be distinct from the name. Use a period (.) to separate a suffix from the name
  • leave Presentation Name field blank (it is inherited)

Do not specify a presentation name for contributing elements because it is inherited from the base element.

The Method Composer tool often provides an indication of the variability type, the content element affected and the plug-in containing the content element affected. It does not do so everywhere, especially in search dialogs. Thus, it is recommended to use the same name as the base as the first part of the name and then include a post-fix to help clarify the plug-in or content package that contains the variant.

To aid in distinguishing between diffierent contributors and the base element, it is a good idea to name contributors differently from the base element.

Replacement

Note:  If the presentation name of the replacement is identical to the element that it replaces, then follow the naming convention for naming a contributor.

A replacing element replaces the original and results in a new element; therefore, follow the conventions for naming a new element. If you are not changing the presentation name, follow the naming convention for naming a contributor.
Extension

An extending element is a new element.  Thus, the name of an extending element should be different from the element being extended.


   

Special instructions when authoring in the UMF: When naming method elements that are to exist within the Unified Method Framework (UMF), specific naming conventions must be used.  For more information, see Guideline: UMF Naming Conventions.

More Information