Example Programs Style Guidelines

[LiliMcDonald]

The Example Program Gatekeepers will be using the Example Programs Style Guidelines and Example Programs VI Analyzer Test Suite when reviewing example program submissions. The Style Guidelines can be thought of as the minimum requirements, but if you think that a particular requirement isn’t suited for your example just explain that in your submission comments.

The VI Analyzer test suite only covers a few of the Style Guidelines requirements so we added a few optional tests to help you find other issues that you might want to fix. The spell check is pretty useful!  Please refer to the attached instructions and download the zip file when you're ready to get started.

Example Programs Style Guidelines
These guidelines were created to promote consistency, understanding, and good coding practices for LabVIEW Examples submitted to the NI Community. What follows is a small subset of the guidelines that are used internally for the shipping examples across the LabVIEW platform. The items in blue are tested in the Community Example VI Analyzer tests.

Example code should be clean, easy to read, and well commented. Examples should also be as minimal as possible, only requiring driver software and hardware if the example cannot be written without it. For example, if the main purpose of your example is to illustrate analyzing data after it has been acquired, consider using a constant or file-based sample instead of actually requiring the user to have certain hardware and drivers to supply data for your example.

File Organization

• Unless you have a good reason not to, name all files (Projects, VIs, libraries, etc.) with full words, and spaces between the words. Some examples:
  • Bad: GenericRTControl.lvproj, AppManagement.lvlib, ExitAllOnErr.vi
  • Good: Generic Real-Time Control.lvproj, Application Management.lvlib, Exit All On Error.vi
• Don’t use the word “Example” in the name(s) of your VI(s).

Icon and Connector Pane

• Ensure all VIs in the example have 4x2x2x4 connector panes, unless a larger one is required.
• Design SubVI icons which are representative of their functionality

Front Panel

• The top-left corner of each example should have a free label formatted as follows:

• Notes about this label:
  • The Overview must be exactly one sentence long. Its intent is to be a quick description of the example.  For a more in-depth description of the example and its motivations, use the community download page.
  • Bold the section names (Overview, Requirements, Instructions).
  • Bold anything you want to stand out in the text. In the text above, Network Streams is bolded because it’s the name of the palette of functions being illustrated, and Simple Network Streams - Host.vi is bolded because it’s the name of another VI you have to run along with this example.
  • Use “or compatible” instead of “or later” in the requirements section to help “future-proof” the information.
• Size the front panel to fit the entire toolbar (i.e., enough to show the search bar), and save it in the upper-left corner of the screen.
• Show the labels of all controls and indicators on the panel, unless you have a good reason not to do so.
• Set clusters to “Arrange Vertically”.

Block Diagram

• Never password-protect any VIs that are part of an example.
• Use an Event Structure to monitor UI interaction where appropriate. Do not poll front panel buttons or other controls when “Value Changed” events in an Event Structure would be more appropriate.
• If there is a “Value Changed” event configured for a control, ensure the control terminal resides in the Value Changed event case.
• Do not configure a Timeout case for an event structure unless there is reason to do so.
• For simpler examples that do not require an Event Structure, use the Wait function (not the Wait Until Next ms Multiple function) to throttle loop execution.
• If your example involves multiple loops, and it is not based on a design pattern like the Queued Message Handler, then include a free label formatted as follows in the lower-right corner of the diagram: “Note: Larger LabVIEW applications typically require a more sophisticated mechanism for stopping parallel loops. To see an example of such an architecture, create a Queued Message Handler project from the File > Create Project” Depending on your design, you may want to point out specific code or patterns that could be problematic if used without modification.
• If your top-level example is not intended to be run, include a VI snippet instead of attaching the VI to the community download page. See this tutorial for more information about VI Snippets.
• Ensure that Auto Error Handling is disabled for all VIs. The error wire should be connected through all diagram nodes, and the diagram should end with a call to Simple Error Handler.vi. This requirement can be ignored for the Simulate Signal express VI.
• Do not create any backwards wires unless they are connected to feedback nodes.
• Do not create wires that travel under structures, or any other block diagram objects.
• Select the “View Cluster as Icon” option for all cluster constants that contain default values for the cluster contents.
• If your example includes its own clusters or enums on the block diagram, make sure they are typedef’ed.
• Use Linked Input Tunnels for state data that is passed through all the frames of Case/Event Structures. Search for “Wiring Tunnels Automatically” in the LabVIEW Help for more information about this feature.
• For subVIs (or top-level VIs that do not have loops), ensure control terminals are on the far left, and indicator terminals are on the far right, of the block diagram. Ensure all control and indicator terminals reside on the top level diagram.
• Ensure there are no calls to obsolete or deprecated VIs, properties, or methods in your example.
• Do not use Stacked Sequence Structures, even for single-frame sequences.
• Ensure Property Nodes and Invoke Nodes are never set to “No Names” view because this makes the code difficult to understand.
• Instead of showing the labels on all subVIs in the example, consider referencing applicable VIs in free label comments, with the VI names in bold.
• Use Subdiagram Labels to document the functionality of subdiagrams in your code.
• Use Wire Labels to document the contents of long wires.
• Think about whether or not your VI needs an error case structure surrounding its contents. If it’s not casing out critical running code (like a high-iteration loop, or a modal dialog), consider just passing the error wire through all diagram nodes without creating a case around the whole diagram.

Miscellaneous

• All example VIs, even subVIs, must have debugging enabled (if possible) in VI Properties. This makes it easier for customers to use tools like Execution Highlighting and Probes to explore the concepts being covered in an example.
• Ensure that the window appearance in VI Properties is set to “Default” for all example VIs.
• If your example consists of more than 1 VI, ensure that all required Vis/subVIs are present and include them in a zip file for submission and download.
• Ensure that any other files that are required to run the example are included. These might be sample data, images, sounds, or configuration files. Always test the file you are planning to submit to avoid delays.
• Include the LabVIEW version in the name of the download. An example might be named “My Custom Sorting Algorithm – LV2009.vi” or “My Custom Sorting Algorithm – LV2009.zip”.