(c) Bruce Powel Douglass, Ph.D. 2019

Sep 5

Where do the lowercase role names for parts come from?


Edited: Sep 5

I've noticed in many books, papers, and model examples that many name their roles in a lowercase fashion and as an abbreviation of the original classifiers. Where did this convention come from and are there other naming conventions?


Example from the SysML 1.5 standard:




See page 234, Figure D.19 - Internal Structure of the Power Subsystem (Internal Block Diagram


There is "fp" for FuelPump or "trsm" for Transmission.


Finally, when documenting our models, in any tool you can provide a description for parts as well as classifiers. I was wondering what the difference is when documenting part and classifiers. I end up usually copying and pasting the description of the classifier into the part as well, but perhaps that is not accurate. For example, in the description for FuelPump you write "The Fuel Pump block is etc. etc." In the IBD diagram, for the part "fp", the descrption would also be "The Fuel Pump block is etc. etc." Something doesn't seem right there, but I have no criteria for differentiating.



A common naming convention is to name types with upper case (either camel case or with underscores) but to name parts, instances, and features (such as value properties) with lower case. I generally follow that convention. Rhapsody, by default, appends "its" to a part, so an instance of block Transmission would be named itsTransmission. I often change the default name to more clearly delineate the role the instance plays. For example, in a CAN bus communication system, I might have two instances of MessageQueue. Rather than use the default names of itsMessageQueue and itsMessageQueue0, I might use receiveQueue and sendQueue.


As to your question on documenting classifiers versus instances; remember that classifiers are types, so their documentation should be relatively instance-context free and instead focus on structure and behavior specified by the type. Instance documentation should focus on the role the instance plays in its context and how it contributes to the collaborations in which it participates.


I don't think it's a good idea to copy the documentation of a classifier into the block; I would document both, but the classifier documentation would discuss its structure, behavior, and possible scope of all uses, but the instance documentation would focus on how that instance is expected to contribute and collaborate. Copying the documentation from classifier to instance has two problems: 1) it is suboptimal, as discussed above and 2) it presents a dual-maintenance problem because duplicated information must be updated in multiple places when it changes.


I hope this helps.

- b

Sep 7

Thanks for the clarification. Indeed, while doing all that copy and paste, the question was on the back of my mind as to whether that was correct or not. While I understand the explanation, one thing remains as a challenge. I have some <<block>> called OperatingSystem or Speedometer. Describing type inforamation is easy. However, role information is more of a challenge. The best I've achieved for OS is simply stating the type of OS chosen like QNX or Linux, or that it plays the role of a safety critical OS. Speedometer likewise is very difficult to distinguish between type and role. Or is there better criteria to use that will help me write better comments in my model elements?

New Posts
  • I noticed a slight change in naming convention for interfaces. Which one is the current standard or recommended guidance? In the Harmony Deskbook 4.1: Interfaces names should be referenced to the sender port. Naming convention: i<Sender>_<Receiver>. In Harmony MBSE Modeling Standards for use with UML, SysML, and Rhapsody: Interfaces shall be named in terms of their semantic concept (e.g. iNavData or FLIRCommands) and their names shall be prefixed with a lower case 'i'.
  • In the Harmony Deskbook there are ActorPins that send events which trigger certain actions in an activity diagram. If I am using UML 2.0, is there a way to model this?
  • When modeling a use case using a sequence diagram, do you use specific values for the values of parameters, or do you depict the parameters themselves? For example, suppose you have a message SetPosition. The message takes two parameters, PosX and PosY. When drawing a sequence diagram where 'A' calls 'B', which is preferred? SetPosition(144, 25) or SetPosition(PosX, PosY) Because it's a use case scenario, I thought using specific values like the first option would be preferred because you are illustraing a particular scenario. On the other hand, the second option is more generic and would apply to many scenarios. However, if you have a scenario, where the flow of control changes based on a particular parameters' value, the second option is not as obvious. On checking the IBM Rational Harmony for SE Deskkbook 4.1, on page 94 for example, they use the second option. In the ALT frame, there is a check on the value of CardStatus for example.