Your Block Diagram Should Be "At a glance readable"

[swatts]

Hello My Beauties,

This ol' blog is approaching a 1/3 million views now, which is a daft number.

A while back I tweeted the following

The point I was trying to make was that some terms are used in software engineering that are not testable. So code must be readable, maintainable blah blah blah. But how do we quantify them? Let's look at readable. 

"Code must be readable", unless you make everything invisible, code is always readable. Actually what we really need is code to be easy to read or I prefer at a glance readable.

How do we go from readable to at a glance readable? Here's some things we do.

Diagrams work best with annotation.

Here's a fairly typical bit of SSDC code, from a design perspective it could probably be a little more abstract*, but it's a pretty good example of the amount of functional commenting we do. This effort allows us to understand the purpose of the BD without going anywhere else.

*SQL shouldn't be visible on the block diagram as this is detail, but the code needed to be light, so we sacrificed a layer.

Left to right...

1. Cluster Element Naming.
2. Select statement with formatting.
3. Some good old fashioned intent comments.
4. Enumerated commands add detail to the icon of the subVI - we know we're using a fetch query
5. Constant Labelling, for columns and rows on arrays this is really helpful.
6. There's a fair bit of code before the case structure, so added a label just to reiterate.
7. True and False Colour coding using subdiagram labels.
8. Another subdiagram label just to clarify whether we update and existing or insert a new.

This can also apply to front panels, you shouldn't need to guess what is an input and output.

Language is important

I know it's hard to believe but I hated English at school, but actually the mechanisms of language are becoming much more useful to my design work.

Noun - a thing <-- what a good object, component or actor is. [Multimeter]

Verb - an action <-- Methods and messages. Things you do to an object. [Measure]

Present Participle - Continuous form of a verb <-- The state of the process (state in a state machine).[Idling]

Command Verb -  A verb used to tell the computer to do something <-- Transition.[Exit]

Cohesion is Important

The biggest problem I run into is lack of cohesion and the issues are commonly as follows.

Not enough functionality - Take calibration for example, to my mind this is 1 VI, you pre-load it channel names and equations. Then input raw numbers and it outputs calibrated numbers.

To my mind anything more is less readable (as well as being difficult to maintain).

VIs that Lie - something is not cohesive because it shares 90% of the data with another function, if you look at a VI and it does more than it promises that's an issue. An example is a VI that takes a query and formats to a table, you may then be tempted to use the query data to do other stuff and your FormatQueryToTable.vi becomes FormatQueryToTableAndLoadCalData.vi. 

I'll be touching on more of this in my NIWeek 2019 presentations.

Program Slow, Debug Fast

Lots of Love