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

[paul_e.bennett at topmail.co.uk]

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