Labels, Labels, Everywhere

 

I’ve had a few long journeys over the last couple of weeks and managed to catch up on some reading.

In particular I have been jumping into some sections of one of my favourite programming books – Code Complete.

As with most books, the practical techniques directly apply to text based languages. Certain things like naming conventions for variables don’t readily apply to LabVIEW since everything is graphical.

However I think we need to think about text as well. It can be fast to read and unanbiguous in meaning (when done well).

LabVIEW supports text documentation, mostly you interact with it through the context help window.

However, as has been pointed out in the last couple of CLA Summits, we should look to reduce the amount we have to break out of our programming flow.

I’ve talked about comments before, but this triggered some other thoughts.

SubVI Names

Increasingly, certainly for internal APIs I find myself mostly relying on text on the icon other than where there is a well establised precendent (Like init or close).

I like this because it makes my code faster to scan, I don’t have to do the mental translation from icon to meaning if it isn’t automatic.

text-for-icon
Example where I have used text for icons

Think about the last time you drew a flow chart? You use text because it is quick and easy to get the meaning across.

(I know this has internationalisation implications, but this has not been a concern for me yet).

I am also aware of an advantage that we do have over C++ and it’s fellows when it comes to writing text. We can use descriptive names for our subVIs since we can include spaces.

Just because C++ has to use names like InitDaqCard() or ReadTemp() because they have to type it all the time. We can use full names for VIs like Initialise DAQ Card.vi or Read Ambient Temperature() and should take advantage of this.

Variables

Pah! Who needs them?

Well we may not name variables (very often) but controls and indicators can and should follow good conventions, with unambiguous names and inclusion of units. Like with the function names we are also not limited by text based languages naming restrictions in the same way.

Reading though, the part that really struck a chord with me though is about intermediate variables.

Code Complete advocates meaningful intermediate names (so not i, j for loop counters for example). This hugely impacts the readability of code.

It actually goes further and suggests forgoing the performance hit and even adding unneeded variables for complex routines where they improve the readability by giving meaning to intermediate values.

Again does this apply to LabVIEW? We don’t have variables?

Actually we do, they are called wires.

When was the last time you drew a block diagram on a whiteboard and left the arrows unlabeled?

It would be hard to read but I find I rarely label wires in LabVIEW (unless they are obviously unclear) and I suspect I’m not the only one.

Some comments but wires aren't clear or are ambiguous
Some comments but wires aren’t clear or are ambiguous

Context to these connections greatly improves readability. Again we may have them in LabVIEW using context help as some names automatically spread from functions.

But if we labeled wires more it could save you using context help, or even opening subVIs to understand what is going on. Do that a few times a day and the productivity adds up.

Larger but clearer with more wires labelled
Larger but clearer with more wires labelled

Oh, and unlike creating an intermediate variable for readability, this comes with no performance implications in LabVIEW!

I will be trying to use them more often over the next few weeks and see how much I can improve the readability of my code.

 

Does this make sense? Or am I completely wrong? Let me know in the comments.

4 Comments

  • Peter

    April 18, 2016

    In my experience, using the text-only icons on internal APIs is perfectly fine. When getting an API out for public consumption (Tools Network, etcetera), I prefer symbols – but they have to be made well. While English is the accepted language in programming, having worked on LabVIEW Localization myself, I appreciate making use of the graphical icons, especially on top-level functions, so the API could be translated more easily.

    On the labels on wires – I love them – I remember when they were first introduced. Especially in classic architectures like a state machine, they clean up my thought process when reading a program. However, oftentimes they could be considered a waste of space and I often prefer commenting on certain parts of the code. I agree that the wire labels are underused, I am excited to learn how using them more affects your code readability.

    Cheers

    Reply
  • Fabiola De la Cueva

    May 2, 2016

    One thing I discovered recently is that once a wire has been labeled, one can hide the label and it becomes the tip strip for that wire! Also, if a subVI is created by selecting a section of code and selecting Edit>>Create SubVI… if the wires going into and out of the selection are labeled, they will be used to label the controls and indicators in the resulting subVI.

    So, make the habit of labeling your wires, if they become a nuisance later, just right click on it and hide the label. The tip strip and the create subVI benefit will stay if you need it later 🙂

    Reply
  • Olivier

    February 7, 2018

    Hi James,
    I strongly agree with you on encouraging text in icons/sub-VI names. Applying a naming and labeling convention throughout the code and project powerfully supports the grail of auto-descriptive code.
    This said, I don’t subscribe to wire labeling. To me, wire labels generally have a too big impact on code surface, resulting in a bad “benefits vs. drawbacks” ratio. Code surface is important in LabVIEW, just like lines of code in plain text languages. The coupling between wire labels and code surface is too strong in my opinion.
    Two important things you don’t mention are constants and structures.
    Labeling constants is critical for both readability and robustness. Boolean constants, for example, usually carry very symbolic, high level information. It is often impossible to guess their meaning without a clear label. Not only this but an inadvertent value shift is just one click away in the diagram and triggers an opposite behavior. Signaling not only the name but also the expected value of a boolean constant helps prevent inadvertent value shifts. In the case of numerical constants, label also prevent “magic values” that cause obscure code.
    Labeling structures is also invaluable. In particular conditional structures (what question does it answer to ?), for loop (what are we scanning ? over which range ?) and while loops (these are often “machines”, “engines” or “process handlers” in LabVIEW).

    Reply
    • James McNally

      February 8, 2018

      Thanks for the comments – this comes at an interesting time as I hope to speak at NI week on a similar topic.

      I think wire labels have strong and weak places. You are right that they take a lot of space and that must be considered. If you have a control, indicator or obvious VI nearby then that can have a strong enough affect to render them redundant. However I think the size is worth it when you have intermediate values in more complex calculations where it helps you to mentally understand the stages or refer back to a formula.

      Constants is a huge one. Not that I use it enough but my VI Analyzer test has a high priority test for unlabelled constants because I think that is key. Using “Constant VIs” when you are reusing them helps with this too.

      Another good resource for this is on Steve Watts blog – https://forums.ni.com/t5/Random-Ramblings-on-LabVIEW/Commenting-I-Like/ba-p/3738636 – the block diagram section is a really nice overview

      Reply

Leave a Reply


By continuing to use the site, you agree to the use of cookies. more information

The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.

Close