On the readability of OSC2 scenarios

@yoav.hollander @pmai: Motivated from the vF2F I will here summarize my current view on the readability of OSC2 scenarios including an example from the IF.

Potential sources of lacking readability

First, I want to start a list of potential sources that may lead to lacking readability (list is definitely incomplete)

1. General issues of program code that lead to poor readability such as
   • bad variable names,
   • too few or not helpful comments,
   • usage of more variables and re-directions than necessary
   • bad formatting
   • ...
2. Issues arising from translation from 1.X to 2.0
3. Deeply nested temporal composition operators

Regarding 1. we already have the coding guidelines in place which I guess will address at least some parts of that point. And in the end, we cannot completely avoid that people write confusing code.

Regarding 2. I think we should put as most guidance into the 1.X migration guidelines to help the people to translate from 1.x to 2.0.

Regarding 3. I would be really interested in how far arbitrary deep nesting of composition operators is useful and necessary and whether there are currently use-cases for that. For me personally it is very hard to really figure out what should happen in a scenario as soon as the composition hierarchy gets deeper.

Example

Let me now give an example where in particular the points 2 and 3 apply.

Consider e.g. the example scenario 02_ALKS_Scenario_4.5_1_CutOutFullyBlocking_TEMPLATE:

In its original form I find it quite hard to understand what should happen without having any information beside the scenario source code. Even if the nesting of temporal composition operators is not too deep (I think there are 3 levels) I had to make small sketch to understand what is supposed to happen there. You can find it as comment to the respective scenario issue.

Another reason for my confusion was the fact that the scenario was translated from a OSC1.X scenario (and I am not that familiar with OSC1.X.) and the Storyboard.INIT phase was translated as a separate part of a serial.

There was a proposal to simplify this scenario by - amongst others - including the Storybord.INIT into the succeeding phase which, saves one level of composition hierarchy and redundant constraints. This is, at least for me, much better understandable even if it has only one hierarchy level less.

Please note that the topic of how to translate the Storyboard.INIT phase from 1.X has a separate issue.

Summary

Regarding 3., I could imagine it to be very helpful to derive further guidelines how to use the language like

• use as few hierarchy levels of temporal composition operators as possible
• try to get along with
  • a serial of parallels (similar to a conjunctive normal form) or
  • a parallel of serials (similar to a disjunctive normal form),
• and choose intentionally which option to use before starting to specify the scenario
• (this of course had to extended to also consider the other composition operators)
• if you really need more levels of hierarchy, then separate the scenario into smaller parts such that each of the sub-scenarios conforms to the guidelines above
• ...

Anybody, please add your viewpoints and comments or add further proposals for guidelines!