Advanced Code Commenting Functionality

[Chris_H.]

Current Situation

The current commenting practice in the BD is to place free floating comment number labels and write the comment in a text field as in the example below.

Disadvantages

- comment number labels do to stick to the code block. if the code number block is moved the comment has to be moved as well.

- no link between number and comment text block

This unsophisticated way of commenting LabView code lead to the lack of comments in general. Usually a new programmer can understand what happens, but not why a function is implemented like this.

Proposal

LabView provides the Advanced Code Commenting Functions.

The comment block is more then just a text block. Basically it has a comment ID, the comment itself and a comment category.

By the context menu the following functions are provide:

1. add comment
2. delete comment
3. move comment up
       The particular comment line is moved up in the comment block. The ID is decremented
4. move comment down
        Opposite from 3.
5. highlight function
        The function to which the comment ID sticks is highlighted.
6. the comment category can be selected. (e.g.. Code Explanation, To Do, )

Adding Comments

Adding a comment in the comment block incorporates two steps (after selecting Add Comment from the context menu):

1. Sticking the automatically generated comment ID to a particular code block just by selecting the item the comment belongs to.

   This could be any type of code: wires, SubVIs, the whole Case, a particular Case, Sequences....

2. Writing the comment

If the mouse pointer is set over a comment ID the comment is shown like a tool tip and disappears as soon as the mouse is moved away.

Advantages

• Comment moves with function block if function is moved on the BD
• Comment ID sticked on the BD item and ID on the comment block always match
• generally more comments in a LabView programm through more simple way of commenting code

[tst]

There have been several ideas posted on the topic of comments in the diagram. I believe this is the earliest - http://forums.ni.com/t5/LabVIEW-Idea-Exchange/Description-and-Tip-like-Help-Hint-Comments-for-Block-...

[Chris_H.]

The major point is that the comment sticks on a certain functionality (e.g. wire, SubVI, case structure, particular case, ...) on the BD.
In my point of view it is annoying to move the comment in addition to the move of any functionality.

[Philbot]

I think the inability to effectivly comment LV programs (from it's simplest form: NXT-G to the latest) is it's greatest Achillies heel.  To the programmers out there that say " The program is self doccumenting... I say... yes, bugs and all.

I also agree that the current method to add comments hails from a bygone era.  Let's get with the 90's at least.

So, ANY and ALL suggestions for improvements should be proposed, considered (and if needed, re-proposed), until one finally sticks.

I like many aspects of the proposed solution.  I would offer some extensions:

1) Be able to right click any item on the BD or FP and select "Add Comment" which would pop up the comment dialog and let me add a new entry to the current comment block.

2) Ensure that the "Print" facility includes and option to print the "comment block" with the commented elements highlighted and tagged as shown in the suggested BD.

Phil.

[Chris_H.]

Dear Phil

Thank you for extensions. Very good points.

I am aware that there are several suggestions to improve the LV commenting and I certainly agree that all of them have to be reconsidered to find the best solution.

Chris

[AristosQueue (NI)]

> I certainly agree that all of them have to be reconsidered to find the best solution.

Unfortunate that most of the commenting suggestions never turn into the big kudos draws (other than the one about hyperlinks in comments). It's almost as if most voters don't document their code...

[Philbot]

>> Unfortunate that most of the commenting suggestions never turn into the big kudos draws (other than the one about hyperlinks in comments). It's almost as if most voters don't document their code...

Indeed, I if a person's first exposure to programming was LabVIEW then they would never had the chance to learn the value of comments.  It's honestly a hardship to try to use them.  Which means that no-one gives them any value.

Luckily the great VI Documentation element built into the help system compensates for the lack of comments at the VI interface level, but not within the VI itself. 

IMHO it's a huge hole in LV's credibility with "Text based" language developers....

eg:  "How good can graphical programming be?  You can't even tie comments to sections of code..."

[AristosQueue (NI)]

> "How good can graphical programming be?  You can't even tie comments to sections of code..."

As much as I'd like to see improvements to the system, I really don't think your comment is a real problem at all.

Labels on nodes. Labels on structures. Labels on terminals. In LV 2010, labels on wires.  None of these can drift away from your code.  Free labels inside frames of a structure can't drift away. Free labels on your top-level diagram are generally the big top level comments that don't really matter where they go. Even given that, the Clean Up Diagram tool now does a good job keeping those labels from drifting off. Then there's actually pasting graphics into your code. You can record the flow chart that is the basis of your state machine, or a picture of the hardware setup that this VI is meant to control. You can do color coding to mark critical sections.

The numbering style is but one style of documenting a diagram. It works really well for example programs where you're ticking off each step-by-step piece in grave detail. That's almost never necessary in actual code. Where it comes close is in translation of dense math formulas into a diagram.

I like the suggestion here -- gave it kudos -- because our system can definitely do better. But if you want to document your VIs, LabVIEW's existing features are at least as good as what exists in a text language, IMHO.

[Chris_H.]

In my team most of the programming work is implemented with text based languages (embedded designs with microcontrollers).

We are used to commenting style like the example below:

void main(void)
{
     WDTCTL = WDTPW + WDTHOLD;                    // Stop WDT
     _EINT();                                     // enable interrupts
     TI_USCI_I2C_DMA_receiveinit(0x48,0x3f);      // initialize USCI and DMA module
     while ( TI_USCI_I2C_notready() );            // wait for bus to be free
        TI_USCI_I2C_DMA_receive(3,array);         // receive the first 3 bytes of array
        LPM0;                                     // put CPU to sleep during communication
}

I really appreciate that every command line can be commented in a simple way with little effort.

That is what a really miss in LV.

[falkpl]

I think the sum of all the multiple kudos shows that Labview needs a new comment mechansim.  A true comment type.  Maybe we need a forum place to consolidate the ideas in one place.

A few I really like are:

1.  Troy K:

2.  Allow meta properties on comments that are user selectable and searchable

    author, date, type{ie bug fix, requirement, comment, todo ....} Number/ID....

3.  Comments should be colapsable

4.  Comments should have an anchor point to any part of a block diagram (ie on a structure,

5.  Comments can be color coded (use selectable)

6.  A robust search/comment viewer should be providid as well as a programatic (vi server) api to allow for our own comment tools to be developed.

IMHO the comment type is long overdue and it should be more a concern of getting this feature right.

We need a good consolidated list to vote on if our input is going to count.

[smercurio_fc]

I'm not sure if this idea is the best way to implement it, but I agree that a better commenting mechanism should be used. I'll vote for this idea so that it gets more visibility, but I would agree that the other ideas should be considered as well to come up with an approach that makes sense and is easy to use for the programmer.