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