Racking Up Technical Debt by Failing to Document Your Code: LabVIEW Rookie Mistake No. 5

Publish Date: Apr 10, 2015 | 6 Ratings | 4.67 out of 5 | Print | Submit your review

If you ever racked up charges on your credit card, you probably learned an inevitable and painful lesson: the day will come when you have to pay it all back (plus more!). It turns out that the same lesson applies to software development, but it’s described in terms of “technical debt.” Technical debt refers to any choice made during software development that trades established best practices for quicker implementation and results in an even greater time commitment or obstacle (“interest”) at some later point to overcome. One of the most common ways that rookie LabVIEW developers rack up technical debt is by neglecting to properly document their code.

 

It’s easy to think that the application you’re working on doesn’t need documentation—you might be experimenting with a new piece of hardware or extending some custom functionality on an existing system. Though that may be true part of the time, you’ll find that investing the time to document up front will save you from losing time on context switching, exposing functionality to users, and explaining your thought process to other developers who use your code.

 

Buffer Yourself From Context Switching

We all know the feeling: you’re immersed in your LabVIEW application, furiously spawning new subVIs, and trying to wire it all together before your meeting in five minutes. Context switching is a reality in today’s world; whether it’s a meeting that your manager called, a text message from your significant other, or that pesky new email indicator, your attention is divided all the time.

 

By leaving yourself some reminder documentation, you avoid racking up future technical debt in the form of retracing your steps (assuming you can even remember said steps). In LabVIEW, these reminders are called “bookmarks,” and LabVIEW 2013 introduced a convenient, elegant method for tracking them called the Bookmark Manager.

 

Figure 1. Use hashtags (#) to create bookmarks that remind you of unfinished tasks.

 

To leave a bookmark, create a free label on your block diagram by double-clicking any blank space. Then begin your label with a hashtag (#) and whichever tag you want to use; “TODO” is a common one. When you come back to your application later, you can choose View»Bookmark Manager and see a list of all bookmarks in your application.

 

Figure 2. Use the Bookmark Manager to see all registered bookmarks in your project. Double-clicking the bookmark opens the VI where it resides and highlights its specific section on the block diagram.

 

Context switching is not going away anytime soon, but you can minimize the technical debt attributed to it by using bookmarks and the Bookmark Manager. Learn more about the Bookmark Manager in the NI Community.

 

Shipping Mystery Code

The further you develop an application, the more comfortable you become with it. In a sense, it is like a familiar friend whom you know so well that you don’t even have to speak to understand what the other is thinking. As close as you and this friend are, your extrasensory perception probably won’t carry over when you’re among other people.

 

Likewise, when you introduce your application to new users, you need to spell out its functionality much more than usual. In LabVIEW, this is called user documentation. Whether your users will be reusing your subVIs or simply running executables, user documentation is intended to help them take advantage of the software with a minimal amount of support from the original developer.

 

Two common forms of user documentation are front panel annotation and VI properties. When you design your front panel, ensure that your controls and indicators have labels, tip strips, and descriptions (accessible by right-clicking the object and selecting Description and Tip). These inform the users of the object’s function while they’re running the VI.

 

Figure 3. Descriptions appear in the Context Help window when you hover your mouse over a front panel object.

 

On the other hand, VI properties allow other developers to reuse your VI in their applications. VI properties typically contain an overview of the VI, instructions for using it, and descriptions of the inputs and outputs (including required, recommended, or optional status for inputs). VI properties are accessible within the LabVIEW development environment by clicking File»VI Properties.

 

If your application already spans many tens or hundreds of VIs, you can double-check that they’re all documented by using the VI Analyzer Toolkit. One of the over 90 tests included with the toolkit checks each VI to make sure that front panel objects have descriptions and tips and that the VI properties are populated.

 

Figure 4. Run over 90 code review tests, including documentation checks, using the VI Analyzer Toolkit.

 

You can never predict how many people will eventually use your LabVIEW application. By writing front panel annotations and VI properties, you have to explain functionality only once instead of describing it to each new user.

 

Creating Your Legacy

All developers should keep in mind that their code will need maintenance, improvement, and expansion performed by other developers in the future. By investing the time up front to document your algorithms, you avoid years’ worth of technical debt. As you develop your application, take the time to write block diagram documentation, in the form of free labels, wire labels, and subdiagram labels, to avoid years of technical support for your successors.

 

Wire labels and free labels point out specific details about program flow and help you document your thought process so that others can pick up where you left off. All wire branches have a label property—just right-click the wire and select Visible Items»Label to reveal it. To create a free label, double-click on any blank space in the block diagram and optionally attach it to a node using the glyph on the bottom-right corner of the label.

 

Block diagram documentation also helps you explain the architecture you chose for your application. For example, in a state machine , it’s a good idea to use subdiagram labels within the state Case structure to explain what each state represents (see Figure 5). Furthermore, in the Producer/Consumer design pattern, subdiagram labels help other developers quickly differentiate between multiple consumer loops.

 

Figure 5. The developer of this example state machine uses wire labels to explain state inputs, subdiagram labels to explain each state, and a free label to elaborate on thought process.

 

As your LabVIEW skills increase, you become a more valuable asset to your company. By documenting the code you’ve already written, you put yourself in a better position to start new projects and advance your career even further.

 

Maintaining the Balance

Your long-term LabVIEW productivity depends on a healthy balance of new development pace and technical debt. Just like a credit card, programming without proper documentation is quick, easy, and devoid of immediate consequences. However, the technical debt you incur can add up over time, preventing you from adding even modest functionality. There are many other forms of documentation (such as Requirements Gateway), but using the methods described here will go a long way toward keeping you debt free.

 

For more information on documentation best practices, access the LabVIEW Core 1 course with self-paced online training (ni.com/self-paced-training).

 

Free access to self-paced online training is included with the NI Standard Service Program and new LabVIEW purchases.

This article is part of a series on the Top 5 LabVIEW Rookie Mistakes

Back to Top

Bookmark & Share


Ratings

Rate this document

Answered Your Question?
Yes No

Submit