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

From: Steve Tockey < >
Date: Tue, 1 Mar 2016 19:37:24 +0000

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.

-----Original Message-----
Date: Tuesday, March 1, 2016 10:29 AM
To: Steve Tockey <Steve.Tockey_at_xxxxxx <systemsafety_at_xxxxxx Subject: Re: [SystemSafety] Modelling and coding guidelines: "Unambiguous Graphical Representation"

On 01/03/2016 at 5:02 PM, "Steve Tockey" <Steve.Tockey_at_xxxxxx
>
>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_at_xxxxxx
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..
********************************************************************


_______________________________________________
The System Safety Mailing List
systemsafety_at_xxxxxx
Received on Tue Mar 01 2016 - 20:37:34 CET

This archive was generated by hypermail 2.3.0 : Tue Jun 04 2019 - 21:17:08 CEST