A question about comments

[Wade]

Hi, all,
I have a question about the comments:
Program function comments should be included on the block diagram or Front panel, or both. Thanks.

[tst]

There is no "should". How to do this depends on the program and on the programmer.
In general, it's convenient to document what each section does and add why you did certain things which may not be clear (like going around a bug in the system) on the BD. That way, when someone looks at the code, they know what each section does.
The user interface should be clear and easy to use on its own. You can write some additional instructions if necessary, but there shouldn't be a need to say what the program does there. You can (and should) write a description of what each VI does in File>>VI Properties>>Documentation.
In addition, I suggest you read the LabVIEW style guide. It has some more on this.

[ian_fung]

Front Panel:
This is usually the GUI to the user, and most of the time, it contains Controls and or Indicators which, normally, self-explained of it function as you would always label them with meaningful description. If further information is require, "Description and Tip..." (Which will pop-up during runtime when mouseover) may be added by right-clicking the intended Control/ Indicator.

Block Diagram:
This is where your code resides. As one's code getting larger, adding appropriate comment(s) to the Block Diagram will help one to manage his/ her code. Of course, approprote sub-vi function ICON will be nice too.

Just a quick thought... and hope I am in frequency!

Cheers!

[Ray.R]

Hi Wade,

I agree with both comments (replies).

Also avoid large cluttered vi's by creating sub-vi's who have specific functionality. That was, you can describe what the vi does, as well as provide a short description of the inputs and outputs to/from the sub-vi. This description will be displayed in the context help (when it is active) by simply passing the mouse curser over the sub-vi icon. Doing so will leave more room in the block diagram for your vi and to keep it clean.

Regards,

JLV

[altenbach]

Many good things have already been mentioned.

For the Front panel, there should be a clear distinction between toplevel VIs (or any subVIs where the user must interact with the front panel), and subVIs where the front panel is only of interest to the programmer. The needs here are quite different:

User Interface VIs
The front panel should be clear and easy to use. All "help" elements, tip strips, etc are geared towards the end user. The icon is irrelevant, because it is typically not even shown. Everything of interest to code maintenance should be on the diagram.

subVIs
Here, the front panel can contain a description of what the subVI does, who created it, company and copyright information, version information, limitations (e.g. input A must be >0), URLs or literature references to the algorithm, etc. (Have a look at any of the openG tools!). The "VI properties...documentation" section should be populated. The icon should be descriptive. All controls and indicators should have intuitive names (not just "Numeric 4", or "Array" ;))

Comments specific to certain areas of the code should be placed where they apply, especially if the code uses some exotic algorithm that would make the code hard to interpret.

Use a programming style that is self-documenting. (e.g. Don't unbundle the error cluster check for "equal zero" to switch a case statement. Wire the error cluster directly to the case so you'll get a red/green error case structure. Much more obvious!)

If these are proprietary VIs with password protected diagrams You should split the comments: Anything of interest to the non-privileged user goes on the front panel, anything else on the diagram. 🙂

In the end, it does not really matters where you place the comments as long as they are easy to find later and still make sense to somebody else 10 years from now. 🙂

Message Edited by altenbach on 05-30-2005 01:13 PM

[Ray.R]

Excellent advice Altenback.

This info deserves a bookmark.

Was this feature implemented by NI? A means of having globally helpful threads stand out so that it does not get lost in the rubbles (dust)??

JLV

[tst]

JLV, are you still with us?

I happened to run into this thread and saw your question.

Assuming that a month later you still consider this "globally helpful", the answer is yes - Click on Thread Options at the top of the thread and select Add This Thread to My Bookmarks. Then, you just have to remember to look at your bookmarks (can be accessed through the dashboard on the top of every page).

[Ray.R]

yes, I am still here..

Although it is nice to have bookmarks, I was proposing some means for new people browsing the forum to easily access (with little or no search) information that should stand out from the "normal / everyday" questions.  Things that would shorten the learning curve.  For instance, it the thread is found to have very interesting info, then it could be tagged (and re-titled?) by certain individuals and a link could be created to (from) another section which only contains a list of these informative threads. 

For instance, a few threads on common questions like serial communication, MAX, GPIB, etc. 

Of course, that may mean less questions... thereby slowing down the gap to the top contributors...  😉

[tst]

After seeing how many beginners gave us the chance to increase our reply number by abusing the floated "Get your Qs answered by LV developers" it seems possible that if we have a link to a FAQ in a prominent location we will need to answer less of those annoying Qs.

So this sounds like a really good idea. 5 stars. How about opening a thread about this in the feedback board where we can discuss this and suggest a topic list for the FAQ?

Then, maybe we'll divide the task between some of the members and get Molly to place a very prominent link to this FAQ (maybe whenever someone asks a question, it will also tell them "check here first").

[Ray.R]

Good suggestion.  I will post a link to this thread in the feedback board.

Thanks.

Ray