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.
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