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.

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

inWater:Water
outSteam:Steam

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

in:Water
out:Steam

But the following is better still:

i:Water
o:Steam

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:

"Trust the Port or Pin Type!" - Often the name of the Type of an anonymous Port or Pin is completely sufficient to indicate its role, unless a clear indication of its direction or unique role is required.

Webel: If you must name your Ports or Pins, name them simply 'i', 'o', or 'io' to indicate direction UNLESS you have to indicate a special role like 'iRole', 'oAuxiliary'. DO NOT use Port or Pin names like 'input', 'output', etc.

FlowProperty naming. Use anonymous or just 'i' for in, 'o' for out, and 'io' for inout. "Trust the Type". For conjugation ~InterfaceBlock use 'o' for in, 'i' for out, and 'oi' for inout.

TIP: SysMLv1: MagicDraw/Cameo: Activity Diagrams: Consider using the Pin display mode 'Name And Type Labels Inside' for 'Position of Labels'. Dr Darren swears by it!

SysML Parametrics: You can use custom stereotypes keywords «i» and «o» on constraint parameters to indicate their intended use (causality) as (i)nputs and (o)utputs on ConstraintBlocks

SysML Parametrics: You can use custom stereotypes keywords «i» and «o» to indicate value properties that are intended to be used as (i)nputs and (o)utputs when bound to constraint parameters for SysML Parametrics

Webel: SysML: Heard of "follow the money"? In MBSE we "follow the flows"! Identify requests, data packets, message, signals early on and use ItemFlow as often as you can wherever you can! Adopt a signal processing mindset throughout (systems thinking).

Relates to

Related notes