Wednesday 27 August 2008

Naming

Names within OOA08's OOA of OOA are represented using a single attribute with a data type of Name. However, names are more complicated than they first appear. Names need to be formatted into numerous formats across various diagrams and generated work products. Letter case will often change during this formatting, as will the separator text before, between and after the words which compose each name. However, even though a name may have many formatted representations, there needs to be an underlying name for determining uniqueness within the context of what is being named. This underlying name needs to be case-insensitive and independent of particular separator text so that uniqueness is maintained in the many formatted representations of each name. A Naming service domain has been created to formalize names and name formats.

The object information model for Naming is given below:

The equivalent class diagram for Naming can also be shown since OOA Tool now supports Executable UML notation:

In the above model, names retain their original Unicode text representation. This representation is converted into a case-insensitive identifier by stripping out all non alpha-numeric characters, including characters such as underscore which are normally allowed within identifiers, and converting the remaining characters into lower case. Since we don't want empty identifiers, all names must include at least one letter. We also don't want any identifiers starting with a digit, so any leading digits are ignored when determining this identifier. The case-insensitive identifier is only unique within certain contexts which is why it is not an identifying attribute in the model above.

Each name is decomposed into one or more alpha-numeric words to simplify formatting. Each word is either all letters or all digits. In the model above, alpha-numeric words contain start and end indexes for the word's text within the original text representation. This also allows us to determine any separating text that precedes the word. This appears to break the normal Shlaer-Mellor rule that attribute values are atomic. However, data values in OOA08 are write atomic but not necessarily read atomic.

Name formats allow letter case to be specified for first letter and secondary letters of first word and secondary words (other replaces secondary in the model above). Name formats also allow acronyms to be preserved even when embedded within CamelCase names.

Name formats are represented using a pattern, the syntax of which is given below:

pattern :=
    textChoices         // Leading text choices
    ( 'A' | 'a' | '?' ) // First word first letter case
    ( 'A' | 'a' | '?' ) // First word other letter case
    textChoices         // Separating text choices
    ( 'A' | 'a' | '?' ) // Other word first letter case
    ( 'A' | 'a' | '?' ) // Other word other letter case
    textChoices         // Trailing text choices
    [ 't' | 'f' ]       // Preserve first acronym case
    [ 't' | 'f' ]       // Preserve other acronym case

textChoices := { '(' { ! ')' $anyCharacter }* ')'
               | '[' { ! ']' $anyCharacter }* ']' }*
Letter case is determined by using 'A' for upper case, 'a' for lower case and '?' for any case. Whether acronym case is preserved acronyms are preserved is determined by 't' for true and 'f' for false (false is the default value). Text choices are delimited by parenthesis or brackets. If any of the given text choices match the actual leading, separating or trailing text then that text choice is used. Otherwise, the first text choice is used. If no text choices are given then the actual leading, separating or trailing text is always used.

OOA Tool's Archetype Language will allow the pattern syntax defined above to be used directly within substitution expressions to control the formatting of text.

Acronyms may span multiple alpha-numeric words since technical acronyms often include digits (e.g. J2SE). However, we need to watch out for 'A' and 'I' which are valid words in their own right. A syntax which summarises the rules for matching acronyms is given below:

    acronym := acronymStart { acronymPart }*

    acronymStart := $upperCaseLetter { $upperCaseLetter }+
                    | ! 'A' ! 'I' $upperCaseLetter
                    | 'A' !! $digit | 'I' !! $digit

    acronymPart := { $upperCaseLetter }+ | { $digit }+

The main name formats used in OOA Tool are listed below:

Name Format Pattern
All Caps Title Case ()AA( )(-)(/)AA()
Title Case ()Aa( )(-)(/)Aa()tt
Upper Sentence Case ()Aa( )(-)(/)aa()tt
Lower Sentence Case ()aa( )(-)(/)aa()tt
All Caps Underscore Case()AA(_)AA()
Title Underscore Case ()Aa(_)Aa()tt
Upper Underscore Case ()Aa(_)aa()tt
Lower Underscore Case ()aa(_)aa()tt
All Caps Camel Case1()AA()(_)AA()
Upper Camel Case2()Aa()(_)Aa()tt
Lower Camel Case2()aa()(_)Aa()ft
  1. Not parsable unless underscore separators used.
  2. Parsable as long as two acronyms don't appear next to each other.

The table below identifies where the above name formats are used within OOA Tool's Shlaer-Mellor and Executable UML diagrams:

WhereShlaer-MellorExecutable UML
Domain Chart domain namesTitle CaseTitle Case
Domain Chart subsystem namesUpper Sentence CaseN/A
Domain Chart prominent object namesLower Sentence CaseN/A
SRM/SCM/SAM1 subsystem namesTitle CaseTitle Case
SRM/SCM/SAM1 subsystem prefix lettersAll Caps Camel CaseAll Caps Camel Case
Upper Camel Case
SRM/SCM/SAM1 prominent object namesLower Sentence CaseN/A
OIM2 subsystem namesTitle CaseUpper Camel Case
OIM2 object namesAll Caps Title CaseUpper Camel Case
OIM2 object key lettersAll Caps Camel CaseAll Caps Camel Case
Upper Camel Case
OIM2 attribute namesUpper Sentence CaseLower Camel Case
OIM2 data type namesN/AUpper Camel Case3
OCM4 state model/terminator namesTitle CaseTitle Case
OCM4 event meaningsUpper Sentence CaseLower Camel Case
OAM5 state model/terminator namesTitle CaseTitle Case
OAM5 accessor meaningsUpper Sentence CaseLower Camel Case
STD6 state namesUpper Sentence CaseTitle Case
STD6 event meaningsUpper Sentence CaseLower Camel Case
STD6 supplemental data item namesLower Sentence CaseLower Camel Case
ADFD7 namesTBDN/A
Thread of Control Chart8 namesTBDTBD
Use Case Diagram namesN/ATBD
  1. Subsystem Relationship Model/Subsystem Communication Model/Subsystem Access Model.
  2. Object Information Model or Class Diagram in Executable UML.
  3. User data type names are formatted in Upper Camel Case while core data type names are formatted in lower case.
  4. Object Communication Model or Collaboration DiagramUML1/Communication DiagramUML2 in Executable UML.
  5. Object Access Model.
  6. State Transition Diagram or Statechart DiagramUML1/State Machine DiagramUML2 in Executable UML.
  7. Action Data Flow Diagram.
  8. Thread of Control Chart or Sequence Diagram in Executable UML.

Name formats within Action Language and Archetype Language code are determined by whoever writes the code. Since uniqueness of names is determined by the case-insensitive alpha-numeric identifier associated with each name, name formats can be mixed within code. However, the following name formats are recommended:

WhereShlaer-MellorExecutable UML
Object/Class namesTitle Underscore CaseUpper Camel Case
Attribute namesUpper Underscore CaseLower Camel Case
Supplemental data item/parameter/variable namesLower Underscore CaseLower Camel Case
Whichever name formats are used in your code, they should be used consistently.