Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 36 Β· Environment and VIs

Clean Diagrams and Documentation

Write readable LabVIEW code: layout rules, wire discipline, naming, free labels, VI documentation and a review checklist for tidy block diagrams.

A block diagram is read far more often than it is written. Messy diagrams are the best-known weakness of graphical programming, but they are almost always avoidable. This lesson gives concrete style rules, then shows a JavaScript stand-in that checks a diagram description against a few of them. The stand-in is not an NI tool; it exists so you can practice thinking in checklists.

Layout: left to right

Data flows from left to right, so arrange nodes that way. Controls sit on the left edge, indicators on the right. Error wires run along the bottom, in a straight line, from the leftmost to the rightmost node. If you follow just this rule, readers can find the start and end of a diagram instantly.

Other layout habits:

  • Fit on one screen. If you must scroll, create a subVI (see connector pane and subVIs).
  • Straight wires. Align nodes so wires have as few bends as possible. Use the toolbar's Align and Distribute tools.
  • No wires behind nodes and no wires that cross a lot. Crossings are sometimes needed, but ten crossings means the layout needs rethinking.
  • Spacing. Leave room between nodes so every wire is visible and probes fit.
  • No overlapping structures unless nested on purpose.
  • Avoid huge diagrams of tiny constants. Group related constants or use a cluster.

Wire discipline

  • Keep wires short and orthogonal (horizontal and vertical).
  • Avoid wire stubs and loose ends.
  • Use wire junctions to split data, but not seven ways from one dot; use a Bundle or a subVI.
  • Name important wires with a free label or label the source terminal.
  • Avoid local variables and global variables where a wire would do. A local variable breaks dataflow because it reads data without a wire, which makes order harder to see and can cause race conditions.

Naming

Name things for what they mean, not for what they are.

Weak Better
Numeric Setpoint (degC)
Boolean Heater On?
String 2 Instrument Address
Cluster Test Settings

Rules of thumb:

  • Use title case with spaces: Sample Rate (Hz). LabVIEW labels allow spaces.
  • Boolean controls end in a question mark or describe the true state: Stop, Is Valid?.
  • Add units in the label or the unit label.
  • Match the front panel label to the diagram label; otherwise use a caption for the panel and a label for the diagram.
  • VI names are noun phrases or verb phrases without abbreviations that only you know.

Comments and free labels

Add a free label (right-click diagram > Decorations > Free Label or just double-click on empty space) to explain why something exists, not what it is. The node already shows what. Good comments:

  • "Wait 10 ms so the loop does not hog the CPU."
  • "Instrument needs 50 ms to settle after range change."
  • "Bug 1423: off-by-one in sample count."

Use a decorative box or a structure to group related code; label the group. For long documentation, put it in the VI Description so it shows in Context Help and in generated documents.

VI documentation

Open File > VI Properties > Documentation and write:

  • A one-sentence purpose.
  • A list of the main inputs and outputs, with units.
  • Any preconditions, such as "Call after Open Instrument.vi".
  • Anything unusual: timing, thread safety, hardware limits.

Also fill in control descriptions (right-click > Description and Tip). The same text appears on hover, so users get help right where they work. NI's Document Generation tools can export VI descriptions into HTML or Word reports.

Tidy diagram rules

Left to right Inputs left, outputs right
Straight wires Few bends
One screen Split into subVIs
Clear names With units
1 / 2

Review checklist

Before you call a VI done, run through this list:

  1. Does it fit on one screen, left to right?
  2. Are all wires straight and visible?
  3. Does every control and indicator have a clear name and units?
  4. Are errors wired through every node that can produce them?
  5. Is there a Stop path that ends loops cleanly?
  6. Are constants and magic numbers explained?
  7. Is the connector pane arranged consistently?
  8. Is the VI Description filled in?
  9. Is there no unused code, no dead branches, no disabled diagram sections left behind?

Dead code can be moved to a Diagram Disable Structure while debugging, but delete it before you finish.

Stand-in: a diagram linter

The stand-in below checks a simple description of controls, indicators and wires against four rules. It is a toy: real LabVIEW has the VI Analyzer toolkit for automated checks. Use it to practice the checklist.

JS Stand-in: tiny diagram linter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The next stand-in shows how much easier it is to read code with a named step per line than anonymous arithmetic. The LabVIEW equivalent is a subVI with a good name.

JS Stand-in: names make logic readable

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check Β· 4 questions

of 4 answered You scored / 4 Β· perfect!

  1. 1. In which direction should data flow on a block diagram?

    Left-to-right layout makes diagrams easy to read and matches the convention.
  2. 2. What should a free label on a diagram mostly explain?

    The diagram already shows what; comments should say why.
  3. 3. Why can local variables be a problem?

    Locals bypass dataflow, so execution order becomes unclear.
  4. 4. Where does the VI Description appear to callers?

    Context Help shows the VI Description when you hover over the VI.

Summary

  • Lay out diagrams left to right, with straight wires, on one screen.
  • Split large diagrams into subVIs and avoid unnecessary local and global variables.
  • Name controls and indicators for meaning, with units.
  • Comment the why, document the VI in VI Properties, and fill in control descriptions.
  • Use a checklist (or the VI Analyzer toolkit) before calling a VI done.

Next: The Dataflow Execution Model