LabVIEW

cancel
Showing results for 
Search instead for 
Did you mean: 

How to document LabVIEW program?

Is there any guidance for how to document a LabVIEW
program?
0 Kudos
Message 1 of 19
(10,877 Views)
The LabView Style Guide has a chapter on documentation. Click here.
Here are some of the things I try to do on every VI.
Create VI Help info: on the VI's File menu, select VI Properties >> Category >> Documentation, then add you help info into the VI Description. That's what will be shown when the user shows the context help (Ctrl-H).
Front Panel:
Create help info for each control: right-click on the control, then select Description and Tip. The Description will be shown when the user shows the context help. The Tip will be shown (as a Tool Tip) when the user moves the mouse pointer over the control, even if context help is not shown.
Make control Labels descriptive. Numeric, Numeric 2, Boolean, etc. are not descriptive enough to be helpful to the user.
Use the control captions if needed.
Use the text tool to add free labels to the front panel if needed.
Diagram:
Show the label for each structure (while loop, for loop, case, sequence, etc.). Not just a free label: right-click on the border of the structure and select Visible Items >> Label. This way the label is attached to the structure and will move with the structure as you're editing the diagram. Make the label descriptive. For loops, summarize what you're doing. For while loop, state when the loop will stop. For For loops, if auto-index is used, state which input will set the number of loops. For cases, describe the criteria for selecting a case.
Within a case or sequence structure, use the text tool to add a free label inside each case or sequence frame to summarize what happens there.
Show labels for all control terminals. Some controls may not have their labels displayed on the front panel (e.g. buttons with their boolean text shown), but always display the label on the diagram.
Liberally use free labels to add more comments.
VI History:
Use it! On any VI window, from the Tools menu (the tools palette), select Options, the select Revision History from the pull-down listbox. Select Prompt for comment when VI is saved. Whenever the VI is saved, add a brief but meaningful comment about what was changed. This history is available under the VI Properties >> Category >> Revision History >> Show Current Revision History (or by pressing Ctrl-Y). It can be very helpful in debugging a program that stopped working after you made a bunch of changes.
Icons:
Create helpful (not just artistic) icons. I typically just use text to show an abbreviated VI name. Graphical icons can be helpful if it's clear to the user what the graphics mean. But I like text. I put my creativity into the program, not into a tiny picture trying to describe the VIs function to the user.
I'm glad you asked the question. The more work you put into your documentation now, the easier it will be for you or anyone else to use and maintain your programs.
Message 2 of 19
(10,877 Views)
> Is there any guidance for how to document a LabVIEW
> program?

good question.

Labview appears (imho) to be inherently undocumentable,
making it difficult for team development,
large projects, revision control, and maintenance.

also, afaik, there is no way (?) to get a 'listing' printout in the
traditional sense, allowing offline study of the program.
0 Kudos
Message 3 of 19
(10,877 Views)
This is a huge question and regardless of the pessimistic comments you will sometimes hear from inexperienced developers, LV is actually much easier to document than less-capable languages such as C. The main point is that the block diagram in a properly-written LV program is your main document.

The ideal when developing LV code is to implement the logic in such a way that the logical flow of the process is visible in the program's dataflows--and like in school, neatness does count. You need to be thinking about documentation throughout the development process so the code illustrates the logic behind the application.

To see what I mean, consider a simple case where logically you want a low output when either input is low--logically an OR-type operation.
One way of implementing this functionality is with an AND gate. Unfortunately, an AND gate describes an operation that is functionally identical, but logicaly opposite (The output is high if both inputs are high.) To create code that expresses the logic, use an OR gate and invert both inputs and the output--a gate that's easy to construct using the multi-input math node.

Having said that, there is definately a need for written documentation as well. In this sense LV is no better or worse than a text language. You still have to describe the logic in words. Personally I have always liked this part of the work because it is the part that helps me make a functional application even better. If you have a hard time giving a written justification for something that might be a good indication that there is no justification for it and the code needs to change.

Also I can't tell you how many latent bugs I have found during the process of logically describing an application.

Mike...

Certified Professional Instructor
Certified LabVIEW Architect
LabVIEW Champion

"... after all, He's not a tame lion..."

For help with grief and grieving.
0 Kudos
Message 4 of 19
(10,877 Views)
pn2500 wrote:
>>Is there any guidance for how to document a LabVIEW
>>program?
>
>
> good question.
>
> Labview appears (imho) to be inherently undocumentable,
> making it difficult for team development,
> large projects, revision control, and maintenance.
>
> also, afaik, there is no way (?) to get a 'listing' printout in the
> traditional sense, allowing offline study of the program.

Are you for real?

Actually, your attitude sound more like you miss the naming of local
variables (which are represented by wires) so that you can puzzle on
ptr, x, x2 and xtemp on a printout over your morning coffee, as if they
were hints in a crosswork puzzle. Or are you more of the type to declare
a variable name in the Hungarian notation (not that the color of the
wire in LabVIEW is virually the same thing)?

Tell me, do you think a Visual C++ project can be documented any more
clearly, or are you just afraid to apply standard software engineering
concepts to your LabVIEW program?

Clearly, there is the vi info property that needs to be filled out. I
suppose in your mind, since the language is labview, this note box is
only filled with trivial things rather than a description of what the vi
does (of course, the vi is not the same as a C function, right?).

Then there are the vi terminals, some are required to be wired, some
maybe not, you have to decalre this. But then again, variable arguement
lists were always a pain C, right? so you might have forgotten about this.

Then, of course, everything has a label. You do take the time to create
informative labels on your terminals, loops sequences and case
structures, don't you? Or not in labview because you dislike the effort
of getting the 'text tool' on your cursor. Perhaps you fear that there
is no easy way to strip out the comments from a LabVIEW program once
they are in, as if you wanted to post your C program on comp.lang.c.help
because you got too confused, but you don't want to give the whole
meaning away to anyone lesser than guru, but I digress...

And really, if you are going to make a flowchart of your C program, will
you be able to edit it in EMACS? Do you use a laser printer or a line
printer for your printouts? If it's a line printer is is 80 wide or 132
wide? When you are writing a program do you write it all down on paper
first, then copy it into the computer? Bwaahahahaha
Message 5 of 19
(10,877 Views)
> Labview appears (imho) to be inherently undocumentable,
> making it difficult for team development,
> large projects, revision control, and maintenance.
>
> also, afaik, there is no way (?) to get a 'listing' printout in the
> traditional sense, allowing offline study of the program.

I think the key here is "in the traditional sense". LV shares much more
in common with CAD drawings than text coding. Oddly modern CAD drawings
were done for more than a century on paper and velum. It wasn't until
the 70's or 80's that computers, expensive ones at that, were suitable
to be used for CAD drawing. To this day, drawings are still the primary
way for engineers to share the info, they can produce lists and other
textual components, but the drawing is annotated and printed on huge
pieces of paper.

I think that LV requires the same sort of techniques for documentation.
First off, you place annotations directly on the diagram. You
sometimes have to add large textual explanations, and may change your
diagram layout to allow them to fit. Other details are better placed in
the description of the various diagram or panel objects. This allows
for interactive viewing, but doesn't necessarily help with printouts
with one big exception. Finally, the documentability of a VI has lots
to do with how it was written. Functions with lots of depth, lots of
nested structures document less well than those that are flat. Kind of
like how mechanical drawings start to span many pages to cover the
layers of a building or machine.

I mentioned an exception above. One of the better things about LV
printing is that you can print out documentation for using the panel,
for using the subVI, or for the source of the VI. These focus on three
different uses of a VI, and in some way resemble the header and source
separation in C, but with much rich info.

The other limitation people are often frustrated with is the size of
their printer. Architects and engineers make $100 dollar printouts
measuring several square feet. This is the best, and in many ways only
way to get your head around the details. When I worked at General
Dynamics, I heard they had flatbed plotters that were something like
eight foot by eight foot. Sadly, most of us are printing on microfiche
by comparison. Several things to keep in mind. If your eyesight is
fine, set the scaling to make more info fit on a page, otherwise, see
about getting access to bigger paper, or do your documentation perusal
online. Afterall, web pages are inherently layered as well, and that
means they don't print very well. Oh well, take your computer to with
you instead of just printouts.

Greg McKaskle
0 Kudos
Message 6 of 19
(10,877 Views)
"Greg McKaskle" schrieb im Newsbeitrag
news:3EEC8BDB.4020005@austin.rr.com...
> The other limitation people are often frustrated with is the size of
> their printer. Architects and engineers make $100 dollar printouts
> measuring several square feet. This is the best, and in many ways only
> way to get your head around the details. When I worked at General
> Dynamics, I heard they had flatbed plotters that were something like
> eight foot by eight foot. Sadly, most of us are printing on microfiche
> by comparison. Several things to keep in mind. If your eyesight is
> fine, set the scaling to make more info fit on a page, otherwise, see
> about getting access to bigger paper, or do your documentation perusal
> online.
Afterall, web pages are inherently layered as well, and that
> means they don't print very well. Oh well, take your computer to with
> you instead of just printouts.

*But* LabView is far off any CAD program in it's printing capabilities.
Actually we've an A0 plotter available but it is a pain printing on it from
LabView (it's a pain to print on a normal A4 printer as well). The printing
is one function that needs much work (did there something change in LV7?).

regards
0 Kudos
Message 7 of 19
(10,877 Views)
> *But* LabView is far off any CAD program in it's printing capabilities.
> Actually we've an A0 plotter available but it is a pain printing on it from
> LabView (it's a pain to print on a normal A4 printer as well). The printing
> is one function that needs much work (did there something change in LV7?).
>

The reason for this is that LV has bitmap content. The nodes on the
diagram are icons, small bitmaps, and those drive plotters nuts. We
talked about getting better plotter support and decided that due to user
icons, we would hold out hope for Windows to deal with it. Plus, the
large plotters at GD, not the super-huge ones, but the large ones were
electrostatic, basically a big laser printer. They didn't have pens.

Anywa
y, the reason I was bringing this up is that a LV diagram is closer
to a drawing than textual code. Just because it is a drawing doesn't
mean it can't be documented and used offline on paper.

As for what changed in LV7 regarding printing, I don't think much but
some bug fixes. Plotters will be no different, but if you see problems
with odd paper sizes -- odd to us -- please report it as a bug so we can
track it down.

Greg McKaskle
0 Kudos
Message 8 of 19
(10,877 Views)

Just make good notes throughout the diagram, especially while you're making the program, and use the print dialog box and play around with all the different options. You'll get used to thinking about how the block diagram will print as you're making new programs, and you'll get good at organizing and labeling in ways which print well like CAD drawings and which follow as straightforward of a logical flow as possible.

0 Kudos
Message 9 of 19
(3,196 Views)

Why resurrect a 16 year old thread?

0 Kudos
Message 10 of 19
(3,184 Views)