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

[Steve Tockey]

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.



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

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.

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.



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

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.



"Try writing meaningful code comments and reviewing them to
ensure the intent matches the requirements. Then coding just
from those reviewed (and approved) comments. Such practice
provides good focus for the coder and done correctly leads to
lean and efficient coding of the application."

Yes, definitely. I call it "Programming by Intent". It's one of the topics
in Chapter 18 of my new book, along with Assertions and Software Proofs of
Correctness.



-- steve



-----Original Message-----
From: "paul_e.bennett at topmail.co.uk" <paul_e.bennett at topmail.co.uk>
Date: Tuesday, March 1, 2016 10:29 AM
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 5:02 PM, "Steve Tockey" <Steve.Tockey at construx.com> wrote:
>
>Derek M. Jones wrote:
>"What is bad code and how does one detect its presence?"
>
>The problem is that "bad code" is a multi-dimensional beast:

Yes. I'll reveal my answers based on my own coding standards.

>Code can be bad syntactically (structurally): long functions (I've
>seen
>3400+ lines in a single function),

The function is to large and needs to be refactored. It is likely that at
this size the interfaces are not that clear either. 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.

> high cyclomatic complexities
>(I've seen
>2400+ in a single function),

Way too high and definitely uninspectable and untestable. (no way
could you guarantee 100% coverage by any measure with that high
a complexity and there is not enough time in the universe to have
covered it thoroughly enough). My own standard suggests that
refactoring should occur if the cyclomatic complexity raises above
seven without a really good justification statement.

> too many parameters on function calls
>(I've
>seen over 40), etc.

Again, a sign that functions need refactoring. Try a limit of 6
parameters without needing explicit justification.

> Much of this could be addressed by
>establishing and
>enforcing a meaningful coding standard. Most, if not all, of this
>is
>detectable using automated tools.

Try writing meaningful code comments and reviewing them to
ensure the intent matches the requirements. Then coding just
from those reviewed (and approved) comments. Such practice
provides good focus for the coder and done correctly leads to
lean and efficient coding of the application.

>Code can be bad semantically: the behavior of the code is
>inconsistent
>with specification and/or user expectation. Call them "bugs" or
>"defects",
>it's the same underlying issue. Testing can help detect some of
>this, but
>not all. Some amount of inspection is probably also necessary.

Agreed.

>Code can be bad pragmatically: bad naming, worthless or misleading
>commenting, etc. This is only detectable by human review of design
>and/or
>code.
>
>Code can be bad holistically: what I mean here is that the code
>could be
>perfect in all other respects but is still a bad fit in its
>environment.

Agreed.

>I'm trying to call out Nancy Leveson's idea that "safety is not a
>property
>of the system alone, its a property of the system in its
>environment" (or,
>however she says it). The code could otherwise be perfect, but
>being a bad
>fit in its environment still makes it "bad code". This may be
>addressable
>by the validation side of verification & validation.

About the only position from Nancy that I could agree with I think.

>
>My point is that it's not a simple thing to precisely define "bad
>code",
>neither is it a simple thing to detect it or repair it.

They say if it was easy everyone would be doing it.

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