Home Community Welcome & Announcements Using the NI Community Document

Using the NI Community

cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

Example Programs Style Guidelines

by Community Team on
‎10-04-2017 04:23 PM
- edited on ‎12-17-2019 02:59 PM by: Community Team

The Style Guidelines can be used as guidance for how to write an Example Program. These guidelines are broken into two sections, guidelines for the information provided in the Example Program document, and guidelines for the attached or linked code.  

 

Example Program Document 

Below you can find the fields to be completed when creating an Example Program in the NI Community and a brief description of each field.  

  • Title 
    • Provide a title for your Example Program document. Try to be as specific as possible while still being concise. A title shouldn’t be much longer than 75 characters. Example: 
      • Voltage Measurement ✖️
      • How to Generate an Analog Output Voltage with a Multifunction Card (E-Series, M-Series, X-Series) and Have the Generation be Based on a Trigger ✖️
      • Analog Output Ramp Voltage Pause Trigger with NI-DAQmx ✔️
  • Language 
    • Select the spoken language that you will use to describe the example code. 
  • Description 
    • Explain what the example shows or demonstrates.  
    • Explain why a user would want to do this task.  
    • Explain other ways that you could modify this example to meet other use cases.  
    • (Optional) Screenshot 
  • How to Use (Optional) 
    • You should use good coding practices to document the sequence of functions and any front panel controls, but you can use this section to document any special instructions you have for the user about how to run the code or incorporate it into their application. 
  • Additional Information (Optional) 
    • Use this section for additional technical background or context a user might need to understand to use the example. 
  • Related Links (Optional) 
    • Use this section to link to supporting documentation or related content as necessary. 
  • Products and Environment 
    • Select the products that were used to create the example, including hardware, software, and operating system. Also document the programming language that was used. Use the Other field to document any other requirements for running the example, such as memory requirements or third-party hardware. 
  • Code and Documents 
    • Attachments 
      • Use this section to attach example code files as well as any necessary documentation for the example. 
    • Third-Party Code Repository 
      • Use this section to link to code repositories that are external to ni.com. Leave this section blank if your code is attached to this document. 


Attached or Linked Code

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:

FrontPanelFormat.png

  • 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”.

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.

Contributors