Webel: SysML/UML: Dr Darren explains HOWTO use concise 'i'/'o' (input/output) Pin and Parameter naming conventions to promote a signal processing mindset in Activity Diagrams. And HOWTO get them compact.

Icon class
far fa-sticky-note
far fa-sticky-note
Note kind
Policy level
Specification keywords
UML keywords
SysMLv1.x keywords
Click on the image to view it full size
This page uses SysMLv1 terminology, but the principles apply just as well to SysMLv2.
These are some naming conventions and strategies that work together for Activity Diagrams (and any underlying Operations), with some options depending on your preferences, which work together to achieve one thing. Dr Darren says:
"Adopt a signal processing mindset throughout all of your SysML modelling!"

I now use these naming convention nearly all the time, for nearly every project involving Activity Diagrams, and where possible even also when using SysML for modelling software code (although sometimes long mandated code variable names thwart it). But for most systems modelling, these conventions are proven to really work well.

For the purposes of the following conventions, 'Pin name' for a CallAction means also 'Parameter name' for an underlying Behaviour or Operation (only because 'Pin' takes less typing).

NB: The heavily annotated SysML Diagram image above mixes and matches some of the naming and display options just for the purposes of pedagogical illustration, it's not completely uniform or consistent.

Some Webel TIPS for keeping your Activity Diagrams flowing

  • TIP #1: Where there is just a single output Pin, use the name 'o', no matter what the Type. That's the single letter 'o', NOT 'out' . Just 'o'.
  • TIP #2: Use very short indicators for input Pin names:
    • Where there is a single input, consider EITHER just 'i' (NOT 'in' ), or 't' or 'iT' to indicate a Type (as long as it doesn't clash with the Type of other args).
    • Where there are multiple inputs, consider just 'i1', 'i2', etc. or 'a', 'b', or 'iA', 'iB' where the letters concisely indicate the Types, which might, say, by Alpha and Beta.

I actually recommend NOT using any numbering implying order, except for Mathematica operations where order matters. From a signal processing point of view, the "order" of Parameters when representing as Pins on 2D CallAction symbols is completely irrelevant (see also TIP #4).

Now compare the following

That's just plain horrible and WET not DRY w.r.t to the Types (no pun intended). This is slightly better:
But the following is better still:

It's not just better because it's concise and lines up nicely cosmetically; it's better because under the Webel modelling recipe the 'i' and 'o' announce that a completely signal processing oriented strategy is being used, they are NOT just parts of the names, they are "code" for a paradigm!

  • TIP #3: Where there are multiple inputs with the same Type, use clear yet concise role indicators to distinguish them (such as 'this', 'that' or 'iThis', 'iThat'), but DO NOT replicate the Type in full in the Pin (or Parameter) names!

As always, endeavour to "Trust The Type!" wherever possible. In this case, it does not necessarily mean completely anonymous, it just means that the 'i' or 'o' names are NOT replicating the full Type name, their job is instead to indicate flow.

And now we get to the creative modelling one:

  • TIP #4: The visual order of Pins for a CallAction or of ActivityParameterNodes DOES NOT have to reproduce the Parameter order of an underlying Behaviour or Operation!
In fact, fussing over Pin order on the boundary of 2D symbols is not only a complete waste of your time, it totally undermines the very advantage of the signal processing idioms that Activity Diagrams support so well!
Dr Darren says:
"Try to think like an electronics designer, or someone soldering and wiring something up on one of those universal freestyle pre-punched PCB boards with holes in a grid."

For example, sometimes it is nice to have ActivityParameterNodes inputs on the left and outputs on the right (or top to bottom) but that is not always optimal. Just "let go" completely and let them float around so the are close to where they are consumed or produced.

Once it's all shiny, consider hiding the Types and just showing the i/o names.

Or alternatively, you can instead "Trust The Edge" to indicate the flow directions, and hide the 'I'/'o' names completely if you do really need to show the Types, but then - if the Types are the same - maybe only on one of either the 'i' or 'o' end of each Edge.

Visit also:
Relates to
Related notes
Related notes (backlinks)
Related snippets (extracts)
Visit also
Visit also (backlinks)