Best practices on how to document code?

[GiovanniV]

Hi,

I tried searching the web for tutorials or examples, but couldn't come up with anything. Can anyone sum up some of their best practices to document LabVIEW code? I'm talking about a fairly elaborate program, built with a state machine approach. It has several subVI's. Since it is important, that other people can understand my code, I guess documentation is fairly important, but NI hasn't got a tutorial for it yet. Maybe a suggestion ?

Thank you for your time! This forum has been a valuable companion already!

Giovanni

PS: I'm using LabVIEW 8.5 btw

[Lucither · Accepted solution]

Giovanni,

Always:

fill in the 'Documentation' in the 'VI Properties'.

Add description to controls in its properties

Label long lines

Label Algorithm's, giving descriptions

Label any code that may cause later confusion.

Use bundle by name when making clusters

Add a description label in loops and cases. Describing the intention of the loop/case

Follow good style guide as will make reading vi's easier and intuitive.

Im sure there are plenty of others i cannot think of....

I would suggest buying 'LabVIEW style book', if you follow what this book teaches you will produce good code that is easy to maintain.

Regards,

Lucither

[Ben]

---

@GiovanniV wrote:

Hi,

I tried searching the web for tutorials or examples, but couldn't come up with anything. Can anyone sum up some of their best practices to document LabVIEW code? I'm talking about a fairly elaborate program, built with a state machine approach. It has several subVI's. Since it is important, that other people can understand my code, I guess documentation is fairly important, but NI hasn't got a tutorial for it yet. Maybe a suggestion ?

Thank you for your time! This forum has been a valuable companion already!

Giovanni

PS: I'm using LabVIEW 8.5 btw

---

Discalimer!

I do not claim to have the best possible code style. How I code is just one example. OThers choose different approaches to documenting and in the end your code will reflect your preferences.

Done with the discalimer.

You may want to take a look at my image gallery starting at page 2 and take a look at the code images I have posted. Yes you have to skip over a lot of Olivia pictures but you should be able to get an idea of how I document code.

If you have suggestions on how I can improve my code documentation, fire away! I ain't dead yet so I'm still  learning.

Ben

[F._Schubert]

Document the state machine. You can use bubble-and-arrow (using any Draw program) or uml (for beginners it is easy to start with dia). Create a png from the diagram and paste it on the block diagram.

Some use a stacked sequence with frame 0 the picture and frame 1 the code.

For the wires of the state machine, it's good if you lable them on both shift registers (outside the while).

Felix

[Ben]

---

@f. Schubert wrote:

Document the state machine. You can use bubble-and-arrow (using any Draw program) or uml (for beginners it is easy to start with dia). Create a png from the diagram and paste it on the block diagram.

Some use a stacked sequence with frame 0 the picture and frame 1 the code.

For the wires of the state machine, it's good if you lable them on both shift registers (outside the while).

Felix

---

That brings up a good point, both sides or just one?

For small diagrams that easily fit on one screen, putting the lables on both sides can somethimes increase the diagram size by 30%.

When the diagrams are small, I usually only lable one side. The other plus with only putting th labels on one side is that I only ohave one set of labels to allign with the SR while two side would require twice as much shuffling.

So I often bend that rule.

Ben

[JÞB]

My code review checklist-

ALL FP objects have:

• Meaningful Label & Discriptive Caption  e.g Label ="error in" Cap="error in (no error)"
• Discription
• Tip for user objects
• Layout simillar to Connector pane for objects wired to CP

BD

• Termials show Label
• Constants show display format (i.e \, n, *, x for strings and b,d,o,x for ints)
• Long wires use free labels
• R-L wires use free labels prepended with "<<" (use sparingly.  but cannot be avoided with FB nodes)
• Logically grouped constructs are explained in comments (e.g. "Init all FP values from File" "Catch and record errors"...)
• Groups of math / bool operations have equasions/ statements in comment
• Utilities that may later be modified have instructions on how to modify.
• Resource descripors are prepended with project mnemonic (i.e. DAQmx Task name "ProjxPowerControl")
• all states/ cases have comment (e.g. "Found Annoying VISA term char warning> clear it")

VI Properties>Documentation: Example

<B>Name</B>
RF Input.vi                           Req section

<B>Functional Description</B>
This Module (FGV, AE, SubVI, GUI, Pop-up) will                                   Thes three words are the best start for this section

encapsulate all of the control for the RFSA in the xx-fff Project.

<B>Modes</B>                                                  (req for Modules and AEs)
Null= Do nothing
Init= Initializes the RFSA
Configure= Selects the RFSA configuration parameters to use
Read Power= Returns the RF Power in band in Measurement
Read Frequency Returns the center Frequency in Measurement
Close= Releases RFSG resource

<B>Type Defs</B>
RFSA Mode
RFSA Config

<B>Author</B>
CCI
J. Bohrer
04 Jan 2010

Add or remove sections "Files", "Globals", "Shared Variables", "History", "Referances"... ad nauseum.

[F._Schubert]

Here come some more suggestions:

Tree VI:

This allows you to group SubVIs in categories (Instrment drivers, File I/O, ...), An approach that will even make it clearer is to use Action Engines to group them together, then the groups are visible using the VI hierarchy window. Also use a consistent color/image coding for the Icons of related SubVIs.

This is also useful to document the layers of hardware abstraction.

Sequence diagram (uml):

This should be used if you communicate with parallel processes via queues, user events and/or notifiers.

Class Diagram (uml):

If you have a pretty complex data cluster, I'd use the class diagram (think about type def's as classes without methods and inheritance). Then using compositions to display sub-clusters as classes on their own.

About labels at shift registers:

I agree that for small diagrams one side is enough. Also they can be omitted if their are controls/indicators with a lable. But their is always a chance that the diagram gets bigger (during developement) or the screen gets smaller (support technican with a small notebook).

Felix

[JÞB]

---

@Ben wrote:

---

@f. Schubert wrote:

Document the state machine. You can use bubble-and-arrow (using any Draw program) or uml (for beginners it is easy to start with dia). Create a png from the diagram and paste it on the block diagram.

Some use a stacked sequence with frame 0 the picture and frame 1 the code.

For the wires of the state machine, it's good if you lable them on both shift registers (outside the while).

Felix

---

That brings up a good point, both sides or just one?

For small diagrams that easily fit on one screen, putting the lables on both sides can somethimes increase the diagram size by 30%.

When the diagrams are small, I usually only lable one side. The other plus with only putting th labels on one side is that I only ohave one set of labels to allign with the SR while two side would require twice as much shuffling.

So I often bend that rule.

Ben

---

---

Of course If you MUST use old LabVIEW verions without Wire Labels the allignment (and BD Cleanup - clean-up) can get to be a headache.  I sell "maintainability" to my customers and explain the life cycle of the systems they are purchasing.  I can usually sell the latest LabVIEW version with this argument. 

But, I do have customers stuck in 6.1 so the point is valid.  So (IMHO) SRs need a label on only one side, since they run straight, either on the terminal(prefered) or outside the loop.  Linked Tunnels need labels on both sides and tunnels that are not linked need just one label.

And Felix brought up some great points.  Any project should have a "Tree vi" with major VIs / Modules on the BD (Hint show labels).  This Makes navagation very easy when you have a few hundred subvis.  And of course, this practice REQUIRES meaningful Icons and VI names or you are just looking at clutter.

[Lucither]

Hi Jeff/Felix,

Could you elaborate a bit more or the 'Tree VI', this is something i have not come across and am intrigued.

Rgs,

Lucither

[F._Schubert]

Just a rough draft during the first coffee:

A Tree.vi or FakeRoot.vi is a vi that is only for documentation purposes.(*)  not intended to run.

You just place VIs on the BD that document the heirarchy of your code. Group them together using single-frame sequences or decorations. Add comments to the groups (like top-level api, low-level functionality, plugin-templates, ...). It's a bit like the heirarchy window, but only showing the important parts of your design.

(*) Apart from documentation, it helps you to propagate changes (type-defs, subVI relinks) to VIs that are dynamically called via vi server. And of course easy access to those vi's (including easy building such projects). Some of this functionality is now obsolete by the project explorer. Original mentioned here long ago by Greg McKaskle

If you have downloaded code from LAVA or use the OpenG tools, search your disk for Tree.vi to find some examples.

Ben, you are the advocate of the tree vi. I'm sure you have more to say on this.

Felix