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

Sep 5

Is there a new naming convention for interfaces in Harmony?

6 comments

Edited: Sep 5

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 simple cases (a single interface between blocks) I use the i<Sender>_<Receiver> or, if I'm using interface blocks ib<Sender>_Receiver>. If the interface is complex enough to warrant multiple interfaces, then I switch the the latter semantic-oriented interface naming convention.

 

Unlike many people, I use the lower case "i" in interfaces because uppercase "I" looks like a one or lower case "L" in many fonts.

Sep 5

While I understand the naming convention given, I was a bit puzzled when I viewed figure 222 of the aMBSE Deskbook. There is an interface called

iACES_Management_ACES_Power between ACES_Management and ACES_Power. The interface has a flowproperty with power and its direction is OUT.

 

Given the naming convention i<sender>_<receiver> I found this strange, because that would imply that ACES_Management provides the power, but we know that is not the case. Of course, this situation is resolved with the conjugation setting on the port on ACES_Management which would then revers the direction to IN. Everything is okay. However, the name of the interface seems misleading to the reader, and that is the situation I'm trying to resolve now before I decide on this naming convention. It's as if the interface is telling the reader "ACES_Management sends power to ACES_Power". What if the interface were renamed to iACES_Power_ACES_Management?

@cramos I used the Harmony Harmony SE toolkit automation which has its own rules. The i<sender>_<receiver> only makes sense when all information specified in the interface is flowing in one direction. This is not generally true, but when it is, the convention makes sense. In this case, the ACES_Management subsystem is the primary director of activities, so I put it in the Sender role even though, in general, flows happen in both directions. This is because systems are more complex than the 4.1 Deskbook would have you believe, one of my issues with it.

I should note that I do not recommend the Harmony Deskbook 4.1. It has many flaws and omissions, which is why I completely rewrote the deskbook as Harmony aMBSE Deskbook, available on this website on the Papers page.

Sep 5

Thanks for the link to the aMBSE by the way. I noticed that in the Deskbook 4.1 for IBDs they were including the superblock in the diagram as well. Whereas the SysML standard states that it is always shown as a frame. In the aMBSE, the example IBDs show it more like it is in the standard.

New Posts
  • 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: https://www.omg.org/spec/SysML/1.5/PDF 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.
  • 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.