[SystemSafety] Modelling and coding guidelines: "Unambiguous Graphical Representation"

Steve Tockey Steve.Tockey at construx.com
Wed Mar 2 19:46:43 CET 2016


Paul,
"On very few occasions have I met cyclomatic compleity above the
magic seven (this is the value that is on the knee of an exponetial
curve of test/inspection effort versus cyclomatic complexity where
the effort really increases rapidly for very little increase in
complexity). The worst was 43 which was actually quite a simple
series of CASE statements (all bounded). That took some time
working through (several days)."

Switch-case is one area of contention with Cyclomatic Complexity.
Clearly--for testing coverage purposes--each one of the cases needs to be
tested (e.g., to get Decision / Branch coverage). On the other hand, as
you point out, switch-case has a very regular structure. My example is a
function that parses a one-letter command from a Command Line Interface
(CLI). It would almost certainly be implemented as a switch-case with 26
cases plus a default for encountering a non-alpha. One would need 27 test
cases to fully cover all decisions / branches. But the true "complexity"
of that code is guaranteed to be a lot simpler than 26 separate if-then
statements--particularly if those if-thens are nested. So I don't have a
final answer on this but I propose to give some kind of "discount" for
switch-case in terms of limiting cyclomatic complexity within a method.
One option is to assess each case as 0.1 instead of 1, so the CLI
switch-case would contribute 2.7 instead of 27. Another option is to
assess it as Ln(cases), so the CLI switch-case would contribute 4.8
instead of 27. A lot of research needs to be done hereŠ

The other area of contention with Cyclomatic complexity is that the
original paper by McCabe charged for ANDs and ORs in the boolean
expression of an if-the or a while-do. My preference is to ignore them for
cyclomatic complexity. This would lead to a better correspondence between
cyclomatic complexity values and control flow test coverage criteria.
Cyclomatic complexity would map cleanly to decision / branch coverage and
the complexities in the boolean expression would only be relevant when one
had to do condition-decision coverage or MCDC. Again, this is just a
proposal, there's clearly nothing authoritative about this.



Re: fan out
"I don't have a figure for that as I am not sure I understand that in a
software context. Electronically I follow the device manufacturers
rules on that topic. Perhaps you would define it for me (privately if
you wish) and I will see where that fits (if at all) in my systems."

The reference is:
Robert Grady, Practical Software Metrics for Project Management and
Process Improvement, Prentice Hall PTR, 1992

Fan out counts the number of methods called from this method. If this
method doesn't call any other methods then its fan out is zero. If this
method calls four other methods then its fan out is 4.

Of course, in the electronics hardware world, fan out is limited by the
current-carrying capacity of the device being connected to.

In the software world, Bob Grady proposes that high fan out suggests
intermediate layers of abstraction are missing. Consider a method,
MethodX(), with a fan out of 15. Suppose that it calls M1(), M2(), M3(),
.. M15(). It's likely that some subset of those calls are cohesive in one
way, and another subset are cohesive in a different way. Maybe M3() ..
M8() are all part of step 3 of the algorithm encoded in MethodX(). Maybe
M10() .. M15() are all part of step 7 of that algorithm. So refactoring
the method with intermediate methods Step3() and Step7() would remove the
M3() .. M8() and M10() .. M15() calls from MethodX() and leave calls to
Step3() and Step7() in their place. The fan out of MethodX() would drop
from 15 to 5, with Step3() having fan out 6 and Step7() having fan out 6.

The contention point in fan out is whether calls to system methods should
count the same as calls to application code methods. I'm undecided on
this, but definitely leaning toward not counting calls to system methods.


Re: number of parameters limited to 4 or 6
"The figure of 6 is based on having to deal with routines that manage
cuboidal data artefacts (X1, X2, Y1, Y2, Z1, Z2)."

Yes, but the mere fact that you've got parameters named X1, X2, Y1, Y2,
Z1, Z2 suggests cohesion between X1 & X2, Y1 & Y2, Z1 & Z2. Assuming
you're in an object-oriented programming language, an alternative would be
to make a parameter class (aka "Data Transfer Object"), maybe called
CuboidCoordinate. You can then (as an example in Java):

CuboidCoordinate x = new CuboidCoordinate( x1, x2 );
CuboidCoordinate y = new CuboidCoordinate( y1, y2 );

CuboidCoordinate z = new CuboidCoordinate( z1, z2 );

myExampleCuboidObject.exampleCuboidFunction( x, y, z );

You've now dropped from 6 parameters to 3, and you're more clearly
emphasizing what was implicit cohesion between X1 & X2, Š

The other part of this is that you shouldn't really have to explicitly
create objects x, y, and z just before the desired call as I showed in
that example code fragment. Whatever function created values X1 and X2
could simply return a CuboidCoordinate since the calculation of X1 and X2
are almost certainly quite closely related.



"I'll take a look at that one when I can. I find that learning new facets
to engineering excellence is always worth the exploration. I might not
adopt wholesale but will select what I think will work for me and my
teams. It is the way I have honed my own development process over
the years to the point that I don't see my systems post delivery (even
though I have used equipment in which some of them are used many
times)."

Yes, I agree. There's almost always something of value embedded somewhere.
The trick is to extract those nuggets and integrate them into a larger,
coherent overall framework. In fact, that's how the modeling method I'm
writing about in my new book came about: integrating previously separate
ideas into a single coherent framework.



Best,

-- steve



-----Original Message-----
From: "paul_e.bennett at topmail.co.uk" <paul_e.bennett at topmail.co.uk>
Date: Tuesday, March 1, 2016 12:47 PM
To: Steve Tockey <Steve.Tockey at construx.com>, Derek M Jones
<derek at knosof.co.uk>, "systemsafety at lists.techfak.uni-bielefeld.de"
<systemsafety at lists.techfak.uni-bielefeld.de>
Subject: Re: [SystemSafety] Modelling and coding guidelines: "Unambiguous
Graphical Representation"

On 01/03/2016 at 7:37 PM, "Steve Tockey" <Steve.Tockey at construx.com> wrote:
>
>Paul,
>
>"My own limit is that
>the function has to fit on one page of A4 paper with more than 50%
>as comment lines. Highest ratio I have had is a 20 line comment for
>a one line functional definition."
>
>Interesting. I don't have a line of code limit. My rule is that a
>method
>comply with all syntactical / structural limits (below) and also
>be highly
>cohesive (aka "single responsibility"), loosely coupled, etc. The
>cohesion
>principle drives methods to end up being pretty short anyway.

I promote all requirements (especially in code comments) meet the
6 C's. Clear, Concise, Complete, Coherent, Correct & Confirmable.

With that in mind the cohesion you seek in modules would seem to
be an easy ask.

>"My own standard suggests that
>refactoring should occur if the cyclomatic complexity raises above
>seven without a really good justification statement."
>
>
>For what it's worth, my standard says 1 through 9 are acceptable
>without
>justification. 10 through 14 are allowed, but only with adequate
>justification. Refactoring must occur at 15 or over.

On very few occasions have I met cyclomatic compleity above the
magic seven (this is the value that is on the knee of an exponetial
curve of test/inspection effort versus cyclomatic complexity where
the effort really increases rapidly for very little increase in
complexity). The worst was 43 which was actually quite a simple
series of CASE statements (all bounded). That took some time
working through (several days).

>I also limit depth of decision nesting (decisions embedded in
>decisions).
>Three levels are acceptable without justification. Two more are
>acceptable, but only with adequate justification. Refactoring must
>occur
>above that.

My decision tree deth limit is three without very strong justification.

>I also limit "fan out"--the number of (unique) methods that can be
>called
>from a method. Bob Grady at HP showed correlation of fan out to
>defect
>density. My limit is 0 to 7 without justification, 8 or 9 with, and
>refactoring at 10 or above.

I don't have a figure for that as I am not sure I understand that in a
software context. Electronically I follow the device manufacturers
rules on that topic. Perhaps you would define it for me (privately if
you wish) and I will see where that fits (if at all) in my systems.

>"Again, a sign that functions need refactoring. Try a limit of 6
>parameters without needing explicit justification."
>
>I don't have an explicit limit on this yet but I read--just
>yesterday--a
>new book that recommends no more than 4 parameters. I'll probably
>incorporate that as "0 to 4 are acceptable without justification.
>5 or 6
>would be acceptable, but only with adequate justification.
>Refactoring
>must occur above that." I need to think more about whether 4 or 6
>should
>be the upper bound for not needing justification.

The figure of 6 is based on having to deal with routines that manage
cuboidal data artefacts (X1, X2, Y1, Y2, Z1, Z2).

>That new book is, "Building Maintainable Software: Ten Guidelines
>for
>Future Proof Code" by Joost Visser (O'Reilly, 2016). I can't say
>that I
>agree with 100% of their recommendations, but it is an interesting
>perspective on things and worth reading.

I'll take a look at that one when I can. I find that learning new facets
to engineering excellence is always worth the exploration. I might not
adopt wholesale but will select what I think will work for me and my
teams. It is the way I have honed my own development process over
the years to the point that I don't see my systems post delivery (even
though I have used equipment in which some of them are used many
times).

Regards

Paul E. Bennett IEng MIET
Systems Engineer

-- 
********************************************************************
Paul E. Bennett IEng MIET.....<email://Paul_E.Bennett@topmail.co.uk>
Forth based HIDECS Consultancy.............<http://www.hidecs.co.uk>
Mob: +44 (0)7811-639972
Tel: +44 (0)1392-426688
Going Forth Safely ..... EBA. www.electric-boat-association.org.uk..
********************************************************************




More information about the systemsafety mailing list