Human Language is Important, Even in Graphical Programming

[swatts]

I hope all you LabVIEW lovelies are doing good.

My brain is rested post-conference and hence I have things to write.

In know LabVIEW is a graphical design language but here's my theory on how the mind works with programming and design.

A well designed program reads like a story in your mind

Thinking back to olden times when I worked in a text-based languages the process would be as follows.

1. I convert the text into images for overall/complex interactions.
2. I convert back to human language for general understanding.

Graphical programming eliminates step 1 in that process, but I still need to convert back to human language to understand what is going on. As an example....

 

When "StopTiming" value changes to true add "Stop Counting" message to bottom of transition queue and set error if appropriate

This has been a theme for much of my thinking on design and can be seen in my writings here and many of my presentations.

This article is my attempt to put this into one cohesive theory.

Cohesion and Naming!

Talking of cohesion, language is a great indicator for a lack of it. Struggling to name your VI, State, Component, Class, Actor is a symptom of poor cohesion.

As a side note I'm becoming increasingly sceptical about abstract "management" Component, Classes or Actors, so anything with the Manager, controller or similar get some critical side-eye.

Another clue is to with connectives, especially logical connectives. These are ANDs and ORs, VIs, States, Components, Classes and Actors should not have any logical connectives.

At the block diagram level try labelling your Structures (While, For Loop etc), again clarity here should make it easy. Any difficulty is indicative of unclear thinking or lack of understanding.

Logic

Try to make logic positive and simple. Once again labelling the positive and negative cases is a great way to ascertain if your logic is too complex.

Positive logic is always easier to understand than negative, studies have shown that bugs like to live in complex and negative logic.

States

Recently I've applied more rigour to my state machine designs and it has been beneficial. See Transitions are Important! - State Machines Done Right

Transitions

See Transitions are Important! - State Machines Done Right

Messages, Responses

For asynchronous or distributed architectures think about the command and response. As an example in DQMH Fabiola stipulates the following.

• Request : Return Operation Mode (Imperative/Command)
• Broadcast : Operation Mode Needed (Past Tense)/Operation completed

Hit me up with some more examples

Lots of Love

[cbutcher]

I think the cohesion and naming section sounds similar to what I've read from Robert Martin in Clean Code, and referenced last year in my GDevCon #1 presentation. I definitely find that when I can't easily summarise what a function does in a short name, then I need to reconsider the function (perhaps splitting or reworking the internals).

The logic stuff is also valuable to read - I have found that when I have the poor fortune to come across code I wrote without this consideration (use positive logic, avoid peculiar combinations of logic) then I spend much longer trying to reason about what will happen, or what I'm really trying to check.

I'll have to give labelling my structures some more effort - sometimes I do this but not in general and I suspect it would be helpful a year from now if I come back. Even when it's clear, an extra hint can speed up refamiliarisation.

[Albert.Geven]

Thanks for formulaating so clearly.

[swatts]

@Christian Cohesion is one of the foundational ideas regarding software design, I still think the original definitions from the late 1960s to be the clearest. 

"The logic stuff is also valuable to read - I have found that when I have the poor fortune to come across code I wrote without this consideration (use positive logic, avoid peculiar combinations of logic) then I spend much longer trying to reason about what will happen, or what I'm really trying to check."

I find writing the logic out as a sentence to be extremely valuable in these cases.

The thing with labelling is that it doesn't actually cost you much time if you do it as you go and the payback always comes sooner than you think.

@Albert Thanks matey.

[joerg.hampel]

"The logic stuff is also valuable to read - I have found that when I have the poor fortune to come across code I wrote without this consideration (use positive logic, avoid peculiar combinations of logic) then I spend much longer trying to reason about what will happen, or what I'm really trying to check."

I used to create my logic in a way that fits the wires, i.e. inverting and restructuring it to the point that all the wires would look the prettiest, with the least amount of bends and crossings. That really didn't help my team members and/or customers with reading my code. 

Nowadays, I don't do that anymore because it makes it really hard for anybody reading the code.

Spoiler

<advertisement>I made that same confession - and more - also at the DSH Workshop, which we'll be giving again on the day after NIDays Europe in Munich</advertisement>

[Intaris]

The problem with humans is that we are conceptually contextual.  Everything we do efficiently, we do within a single context.  Whenever we need to switch context, we need a while to get back up to speed. In order to get to the "flow" state, context needs to be consistent. As with LabVIEW run-time engine, context switches can be expensive. Code that has the observer constantly switch back and forth between contexts is so annoying and exhausting to debug..... Inconsistent logic is a huge deal breaker. Nothing make a context awkward like conditions, sometimes ;).

For me, cohesion and naming are tools to make the context clear and stable when reading.  We say that code should have only a single responsibility, maybe our diagrams should strive to have a single context.

Now, if only we could clearly define what "context" is.....

[swatts]

Hmmm "context", that's interesting thinking that is Shane....

[FabiolaDelaCueva]

I tell people during design and code reviews:

"If reading a model of your code, or your code itself, out loud doesn't make sense, chances are it won't work as expected."

It is interesting how we equate coding with math but sometimes, like in this case, it might be closer to writing than calculating. Expressing ideas clearly in prose is an art, expressing ideas so another human understands them and the computer can compile them is an art as well.

Thanks to Steve for sharing with us, you have a knack for making complex things clear and I love reading these discussions.

Regards,

Fab

@Joerg, I saw what you did there! nice 😉

[Dhakkan]

Steve,

The timing of your opening post was quite the coincidence. I was reading an article in Kent Beck's 'Guide to Better Smalltalk: A Sorted Collection'. In 'Think Like An Object', the author writes about always having a dictionary and thesaurus handy when designing!

Plenty of good advice in that chapter, I highly recommend it to OO designers.

Incidentally, I wonder if any of you folks have come across or used CRC cards (Class-Responsibility-Collaborator) approach to design?

Vishak

[swatts]

Thanks Vishak,

I'll look that up