Overhaul the LabVIEW Style Checklist inside LabVIEW help

[fefepeto_kb]

The help page, that is supposed to provide a starting point for the developers on creating readable, high quality code in LabVIEW seems to be unchanged for quite some time: LabVIEW Style Checklist - NI.

At different workplaces (including NI) and different teams I have seen different implementations of such guides, many of which included extra "rules".

One such example is the file naming convention:

• Using spaces for separating words.
• Using Libraries to namespace VIs instead of including the noun in every related VI.

These are the most prominent examples I can come up with from the top of my head, but I'm sure that there are more.

I'm curious if an updated version exists somewhere that could be used to replace the above refenced help page?

If there is not, then I think could we collect some ideas here for updating this document.

[Petru_Tarabuta]

1. Thanks for referencing the LabVIEW Style Checklist help page. I was not aware of it. Based on a quick skim, it seems to contain lots of useful advice. I hope to read it in full sometime.

2. "seems to be unchanged for quite some time" - The following is written near the top of the page: "Updated 2024-07-16". This suggests the content was updated recently. Are you sure that the content is outdated?

3. A potentially useful resource is the DQMH Style Guide.

4. IMO many of the VIs that ship with LabVIEW (for example, the VIs that reside inside vi.lib) could and should be refactored (even if just through cosmetic/non-functional changes), such that they adhere to a consistent and professional style.

[fefepeto_kb]

Bună ziua!

For the 2. based on my NI past: this is the time of posting the content not the last update, i.e.: the date when LabVIEW 2024 Q3 help has been updated (maybe a few days before becoming available to the public).

3. Thanks for the reference, I did not know about that.

4. Definitely, but that would be a separate idea, and potentially a lot more effort.

[joerg.hampel]

Besides the DQMH Consortium Style Guide Petru pointed out (which targets LabVIEW in general, not only the DQMH Framework), there's also the HSE Dokuwiki:

https://dokuwiki.hampel-soft.com/kb/bestpractices/codingconventions

We ask all our peers (i.e. customers and subcontractors) to follow these coding conventions to help improve the readability of their source code and make software maintenance easier. Every single guideline comes from a situation in real life where we were bitten by something, discussed the best way of dealing with it in the future, and then codified it into our wiki.

[Petru_Tarabuta]

Thanks! "Bună ziua!" means "Good day!" in Romanian. It's impressive that you got even the accented letter "ă" right, instead of a regular "a".

I also agree with everything that you and Joerg wrote above.

[fefepeto_kb]

Pssst! "ă" was a cheat. Being born and raised in Romania, that's natural.

Thanks for the HAMPEL coding conventions.

[raphschru]

Really nice documentation @joerg.hampel, I wish our company had something like this! Btw it is much more readable, structured, navigable and better formatted than anything NI did with their new format (quite faster to load too!). Have you thought about giving NI some documentation advice 😁 ?

After reading it, there are some points I'd like to discuss (quotes in blue) :

Style:

Use system controls (enable in Options → Front Panel → Control Style for New VIs)

► I wouldn't set System by default for all VIs, because the System palette is missing several categories (Data Containers, I/O, Variant & Class, Refnum). In case you need these extra categories, you would have to use another palette (e.g. Modern) and then have mixed-style VI front panels for your non-GUI subVIs. For GUI VIs though, System is perfect!

„Tools – Options → Block Diagram → General“ unceck option “Place structures with Auto Grow enabled”

► Why? It avoids having hidden code outside structure borders, for which LabVIEW gives no warning (unless using VI Analyzer of course).

Conditional Disable Symbols case sensitivity

• True value is spelled TRUE (all uppercase)
• False value is spelled FALSE (all uppercase)

► This contrasts with the built-in RUN_TIME_ENGINE symbol where allowed values are either "True" or "False".

General:

When working with clusters and SubVIs, pass only the data the SubVI needs. Do not let the SubVIs consume the entire cluster.

► Why? When using classes instead of cluster, the whole data is passed anyway, and using classes is the recommended way for complex architectures. Is it because of performance issues?

Functions and Primitives:

Do not use “First Call?”, use an FGV instead

► Why? It is useful e.g. for loading a static resource only once. Btw, if you want to eliminate stateful functions, you should eliminate FGVs too, and pass all data by wire.

Use Compound Arithmetic instead of boolean logic gates

► I find the visual difference between AND/OR/XOR harder to spot with Compound Arithmetic compared to the logic gates.

Block Diagram:

Background color of block diagram is grey (RGB = 226/226/226; 'Indicator Background') where applicable

► I suspect this is an error and is rather the background that should apply to the Front Panel.

Finally a general navigation improvement idea: there could be buttons at the bottom of the documentation pages to go to previous/next topics 😁.

[fefepeto_kb]

I think I can chime in for some of the concerns and Jörg might confirm them or provide other perspective.

„Tools – Options → Block Diagram → General“ unceck option “Place structures with Auto Grow enabled”

► Why? It avoids having hidden code outside structure borders, for which LabVIEW gives no warning (unless using VI Analyzer of course).

This saves time during edit. For example If you start typing a longer string constant, free label the structure resizes. The issue begins, if the structure is nested and everything starts to resize, but things that are outside of the outmost structure with auto grow enabled will not align anymore. Cleaning up that part is usually more time consuming than pre-extending the structures and simply adding the new code in the empty space. I did not believe this until I tried out either, but this is the only way I'm coding now.

When working with clusters and SubVIs, pass only the data the SubVI needs. Do not let the SubVIs consume the entire cluster.

► Why? When using classes instead of cluster, the whole data is passed anyway, and using classes is the recommended way for complex architectures. Is it because of performance issues?

I think this is a specific example of a bit wider problem. Inside NI I seen multiple guides pointing out to avoid making copies of data, especially if the data is large.

Do not use “First Call?”, use an FGV instead

► Why? It is useful e.g. for loading a static resource only once. Btw, if you want to eliminate stateful functions, you should eliminate FGVs too, and pass all data by wire.

First call is a tricky operator. Inside NI we burnt ourselves a few times with it. The problem is, that first call used for a VI is unpredictable in at least this corner case: the VI is called multiple times during a test execution, but it might be unloaded from the memory either automatically to free up RAM when it gets close to 100% or when the calling VIs are explicitly unloaded from memory to avoid memory issue. In these cases the first run operator returns true, even if the VI did execute before unloading, while the expected value might be false. For the use case you mentioned it won't make a difference, but if you need to know if the VI did run and did something to the hardware then it might cause problems.

Use Compound Arithmetic instead of boolean logic gates

► I find the visual difference between AND/OR/XOR harder to spot with Compound Arithmetic compared to the logic gates.

This ensures that the code is easy to expand when needed therefore increases maintainability at the cost of readability. Considering the use case for which the guide was created, I think maintainability is more important.

[joerg.hampel]

Thanks for the great questions, @raphschru! You know that our wiki is public for a reason - just steal everything and make it a starting point for your company's documentation 🙂

And WOW - thanks, @fefepeto_kb, for chiming in - spot with all you say 💜

Here are my thoughts (obviously in purple)... I will preface this by stating that:

1. The whole documentation is aimed at working in small teams with varying proficiency. That is our one single point of focus. We will happily compromise performance and other things if we think it'll help the team collaborate more easily and efficiently.

2. Most of the items are a tradeoff and a personal/team choice. If anybody doesn't agree, that's perfectly ok.

3. We might be wrong in places, so I appreciate you challenging us!!

Style:

Use system controls (enable in Options → Front Panel → Control Style for New VIs)

This mostly aims at UIs, maybe that should be mentioned. We're currently looking into moving to custom-made controls and/or the Fuse design for newer LV versions. 

„Tools – Options → Block Diagram → General“ unceck option “Place structures with Auto Grow enabled”

As fefe says - we size our structures manually, and that is cleaner and faster. Seeing as we work a lot with DQMH, I do not appreciate LabVIEW guessing how I want things inside stacked structures (case inside loop inside error) to move, I will take care of that manually. And yes, VI Analyzer catches any hidden code.

Conditional Disable Symbols case sensitivity

• True value is spelled TRUE (all uppercase)
• False value is spelled FALSE (all uppercase)

You are right... Honestly, I cannot remember why we settled on all caps. There was a discussion though. The important thing back then was to have a standard across our team/customers.

General:

When working with clusters and SubVIs, pass only the data the SubVI needs. Do not let the SubVIs consume the entire cluster.

► Why? When using classes instead of cluster, the whole data is passed anyway, and using classes is the recommended way for complex architectures. Is it because of performance issues?

This is one of the big issues I have with LVOOP, and it's 100% about readability. Feeding the class wire into every method VI completely hides the information of what it actually needs. For clusters, you don't want to do that. I want to see which data the VI consumes and modifies.

Also, not tying every single SubVI to the complete mothercluster will maximise reusability. Again, I'm thinking about DQMH, and how you don't want to link all your subVIs to the DQMH data cluster.

I can feel my blood pressure rising just talking about this 😛

Functions and Primitives:

Do not use “First Call?”, use an FGV instead

Like fefe says, First Call? makes it difficult to execute code multiple times without unloading first. And even then, there are corner cases. It's a definite no for us.

Thinking about it, I don't think that functionality should be required anyhow. Most times, there will be something to check instead (like, has the config cluster been populated? Is the TCP reference valid? Is the DQMH module running?...) 

Use Compound Arithmetic instead of boolean logic gates

► I find the visual difference between AND/OR/XOR harder to spot with Compound Arithmetic compared to the logic gates.

This is about standardisation - we agreed that sticking with one of the two makes code more readable. As fefe says, sometimes you want/need the CA, so we decided to stick to it for all use cases. Once you embrace this solution, code is more readable in our opinion.

Block Diagram:

Background color of block diagram is grey (RGB = 226/226/226; 'Indicator Background') where applicable

► I suspect this is an error and is rather the background that should apply to the Front Panel.

Nope, it is what we used to do - have the bg of the BD be grey, and then have the encompassing error structure with white bg - this will draw your eyes to the important part of the BD. I still love this, but seeing as we're sharing a lot of our code publicly these days and also consume 3rd party code, it's impossible to keep our code base consistent. This guide item will probably go away. 

Finally a general navigation improvement idea: there could be buttons at the bottom of the documentation pages to go to previous/next topics 😁.

Love it - done!

Again, please keep the questions coming. Feel free to disagree, and please don't hate us for having a different opinion in some cases 💜

[Christina_R]

We've posted an updated version of the VI Style Guidelines that we use internally at NI: Style Guide - LabVIEW Wiki

We decided to put it on the LabVIEW WIKI so that the LabVIEW Community is empowered to evolve the guide, and/or link to the other style guides that exist.

I haven't yet decided what we're going to do with the style guide content in the LabVIEW manual, but we'll probably remove the specific guidelines and reference community-based style guides instead.

[fefepeto_kb]

Hi Christina!

Many thanks for sharing the link to the style guide, and also for sharing the internal one to the community.

Please forward my thanks to the original author too.