The Importance of Documentation
Sorry for the long delay in posting. Between my three-year-old twin boys, three-month-old twin girls and working hard on getting the next version of LabVIEW for the Mac in great shape, I've been a bit busy.
I've noticed recently what a difference it makes having polished VIs. By polished, I mean well documented, consistent connector panes and a general overall consistency. With all the dialogs to get at the various information and set documentation on controls/indicators and VIs it can be a bit time consuming and difficult to make sure everything is consistent, but it is worth it.
In 8.2.1, you not longer use Command-H to show/hide the contextual help window (which is the system Hide LabVIEW command), you use the Help key (or if you have a MacBook, Command-Shift-H). The contextual help window is your guide to understanding code on the block diagram.
So the places to document your VI are:
1. File -> VI Properties -> Documentation
Set the VI description to some helpful text on what the VI does and how to use it. Also create an HTML file for further documentation. You can have just one HTML file and use anchors <a name="test"> for each VI. The Help tag is the name of the anchor. (NOTE: as of 8.2.1, you must manually escape any spaces in the anchors/Help tags, for instance <a name="test me"> would have a help tag of "test%20me").
While you are in VI Properties, visit the following pages also:
- Protection: make sure the password protection/locking is how you want it.
- Execution: make sure Allow debugging and Enable automatic error handling are turned off (if desired).
- Window Appearance: Make sure the window title is what you want it to be
2. Right-click (control-click if you don't have a mighty mouse) on each control/indicator that is in the connector pane (and possibly others) and select Properties -> Documentation and make sure the description is meaningful, as well as a short description in the tip strip. Also Right-click on each control/indicator in the connector pane and make sure that its Required/Recommended/Optional is set correctly. Also make sure that all controls and indicators that you meant to have on the connector pane are there.
You probably want to visit similar controls/indicators on each VI, instead of visiting each control/indicator on a single VI. For instance, visit all the "error in (no error)" controls on all your VIs, to make sure they are named the same and have the same (or consistent) descriptions, then go on to "error out" and any other common data types. The idea is to make sure you are consistent.
3. Right-click on the following elements of your Project window and select Properties:
- Project Node (My Project.lvproj)
- Library Nodes (MyLib.lvlib)
- Class Nodes (MyClass.lvclass)
etc.
Go to the Documentation page (in the project case, its the Project Description) and fill in the information in a similar way.
Doing this has three benefits:
1. The next person who needs to modify the project (or you in 6 months) will have plenty of documentation on how it works and how to use it.
2. If you product is meant to be used by other LabVIEW developers (a library or class meant for other to use) will have an easier time learning how to use your code correctly.
3. While you document you code, you find things you missed. It forces you to think through how things actually work, and helps you find problems or missing elements.
To simplify the documentation of VIs (not other project items like classes and libraries), I have written a tool that walks through all the VIs in a project and allows you to see in one place all of the VI information and allows you to update it in one place.
As you can see by clicking on the image to the right, you can easily navigate through all VIs in a project, and all terminals in a VI. You can also connect/disconnect terminals, rename terminals, add documentation to terminals and VIs, set the window title, set debugging and auto error handling and see how it all fits together in one screen.
If you are interested in trying out this tool, you can email me at Marc dot Page at NI dot com, and I will reply with a zip file containing this tool.
I've noticed recently what a difference it makes having polished VIs. By polished, I mean well documented, consistent connector panes and a general overall consistency. With all the dialogs to get at the various information and set documentation on controls/indicators and VIs it can be a bit time consuming and difficult to make sure everything is consistent, but it is worth it.
In 8.2.1, you not longer use Command-H to show/hide the contextual help window (which is the system Hide LabVIEW command), you use the Help key (or if you have a MacBook, Command-Shift-H). The contextual help window is your guide to understanding code on the block diagram.
So the places to document your VI are:
1. File -> VI Properties -> Documentation
Set the VI description to some helpful text on what the VI does and how to use it. Also create an HTML file for further documentation. You can have just one HTML file and use anchors <a name="test"> for each VI. The Help tag is the name of the anchor. (NOTE: as of 8.2.1, you must manually escape any spaces in the anchors/Help tags, for instance <a name="test me"> would have a help tag of "test%20me").
While you are in VI Properties, visit the following pages also:
- Protection: make sure the password protection/locking is how you want it.
- Execution: make sure Allow debugging and Enable automatic error handling are turned off (if desired).
- Window Appearance: Make sure the window title is what you want it to be
2. Right-click (control-click if you don't have a mighty mouse) on each control/indicator that is in the connector pane (and possibly others) and select Properties -> Documentation and make sure the description is meaningful, as well as a short description in the tip strip. Also Right-click on each control/indicator in the connector pane and make sure that its Required/Recommended/Optional is set correctly. Also make sure that all controls and indicators that you meant to have on the connector pane are there.
You probably want to visit similar controls/indicators on each VI, instead of visiting each control/indicator on a single VI. For instance, visit all the "error in (no error)" controls on all your VIs, to make sure they are named the same and have the same (or consistent) descriptions, then go on to "error out" and any other common data types. The idea is to make sure you are consistent.
3. Right-click on the following elements of your Project window and select Properties:
- Project Node (My Project.lvproj)
- Library Nodes (MyLib.lvlib)
- Class Nodes (MyClass.lvclass)
etc.
Go to the Documentation page (in the project case, its the Project Description) and fill in the information in a similar way.
Doing this has three benefits:
1. The next person who needs to modify the project (or you in 6 months) will have plenty of documentation on how it works and how to use it.
2. If you product is meant to be used by other LabVIEW developers (a library or class meant for other to use) will have an easier time learning how to use your code correctly.
3. While you document you code, you find things you missed. It forces you to think through how things actually work, and helps you find problems or missing elements.
To simplify the documentation of VIs (not other project items like classes and libraries), I have written a tool that walks through all the VIs in a project and allows you to see in one place all of the VI information and allows you to update it in one place.
As you can see by clicking on the image to the right, you can easily navigate through all VIs in a project, and all terminals in a VI. You can also connect/disconnect terminals, rename terminals, add documentation to terminals and VIs, set the window title, set debugging and auto error handling and see how it all fits together in one screen.
If you are interested in trying out this tool, you can email me at Marc dot Page at NI dot com, and I will reply with a zip file containing this tool.
Labels: Coding, Computers, Documentation, Good Code, LabVIEW, Mac, Mac OS X, Macintosh
posted by Marc | 8:06 AM
4 Comments:
Thanks Marc! Always good to know that documentation is appreciated ;-)
If anyone wants to know more about the documentation in LV, visit my blog here: http://lvtechspeak.blogspot.com/
This looks really nice. I often navigate between the dialog boxes for description & tip and VI documentation and perform cut/paste. This would make my life easier.
I suggest that you make this available via community.ni.com to reduce your emails and offer you some revision control. I recently downloaded the Palette API written by Qizhen Ruan via community.ni.com and its very useful.
Thanks ryan. I enjoyed reading your blog, keep it up.
phillip, you make a good point. I have posted the Polish VIs project at:
http://community.ni.com/examples/polish-vis
Hello Marc:
I have been looking at your blog for a while, hoping to see some hint that NI will actually at some point upgrade NI-DAqmx base for OS X The support is abyssmal, with an extremely crippled Base version that doesn't support many of the hardware features on the board and documentation that is also very limited. Is there any means to get some kind of beta version of a more advanced version of mxBase?
Post a Comment
<< Home