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

[Mark_Yedinak]

While I agree that LabVIEW could use some improvements in its commenting I would prefer to have the comments with the block of code itself rather than in some other large comment block with an ID. Anything that results in my having to look at two places to read the comment and view the code would deter from the usefulness of the comment. There is also the age old debate about comments in code in general. The comments are only good if they are maintained and kept up to date. Excessive comment blocks should probably be avoided since these will more than likely not be maintained and it leads to more confusion and bugs if the comments and code say two different things. Large comment blocks are also a sign of overly complex code. Smaller, simpler code will generally be easier to understand and maintain. If you need to write a short story explaining what is happening in the code it is probably time to refactor the code.

Like smercurio_fc I voted for this to get visibility to improving LabVIEW's commenting ability but I am not sure I agree the "footnote" approach is the best method.

[PatrickC]

These ideas all sound very good and are related to things that we have been brainstorming here in the LabVIEW team. Important ideas I see here that we'd like to address:

1. Attachability - Comment should stay with the code it relates to and can be created in this fashion, as well as attached after creation.
2. Collapsability - Comment should be able to shrink down in size to a flag. Show/hide options for individual comment and whole diagram's comments. A question here - if we had a separate window where you could browse comments, would you still want to be able to see them on the diagram (Hover would still show, but to see all at once)? The tradeoff here is whether managing the location of the comment on the diagram when non-collapsed is useful or just a burden.
3. Tagging - Should have capability of more than just text, but metadata tags that are easily searched. I would put color in this category. What are the standard metadata (color/user/time/numbering shown in previous comments) that should be supported? Can users create their own, and what are the advantages over just text with search?
4. Programmatic - What features would you expect of programmatic API? Just search text/tags? Create/delete? Just go general purpose and say everything you can do in the editor?

 Are there others that I've skipped?

Thanks,

Patrick

[X.]

To add to the functionalities mentioned above: the capability to include link to other objects in the diagram or panel and even more useful, to other VI diagrams.

This would be particularly useful for all dynamic calls, clients or producers of queues, notifiers, etc... For instance, I'd love to be able to define a virtual folder in my project that would contain all VIs acting on/reacting to a queue and be able to link to it each time I use that queue. Right now, I rely on my memory for this kind of things, but that's not a reliable tool for the long term.

In fact (but that would be a whole idea to explore for its own sake, and I think not limited to LabVIEW), there is a need for tools to visualize the relationship between modules that communicate "indirectly" (the definition being imprecise on purpose). Another layer of diagram to draw "wireless" relationships?

My 2 cts.

[LuI]

Well, I do (and have to) comment my code without all the additional features. Just have a coloured text rectangle below or inside the structure to comment. Have a consistent colouring scheme (in my case: light green with dark green border and black text for comments and light yellow with red border and black text for warnings, ToDos etc. If those ToDos are are partially done, I change their color for the finished part to blue.

And the most important part: Use a version control system and save your work at regular intervals. Drop a comment on why you saved (which in my case is either 'intermediate saving', 'save bvefore test', 'tested: <Status>' or a comment explaining what the new functionality does (or is expected to do).

[MrQuestion]

I really like this idea. Sometimes you just don’t have enough room to add good comments. A programmer shouldn’t have to decide between good comments or cosmetics.

If this is implemented it would be nice to add an additional feature. Not intending to hijack this feature suggestion but it would be nice to have a method to extract the comments externally.

We are using SVN for source control. When we commit the VI's to the repository it would be nice to have the ability to extract out any added comments from the VI and have them place into the SVN commit notes. This allows programmers to look back in time and better track changes.

Before people start complaining about SVN and NI I don't expect NI to support every type of source control management out there. I just want a method of extracting all comments. And, yes I understand that it would probably be a garbled mess, but it is easier to delete unneeded text than to recreate comments.

I currently use a text parser that extract out the first part of the binary VI where the VI document description is encoded in ascii and then add this to my repository for the initial comment. If you open a VI in a text editor you will see your VI document in the first part of the file.

In well documented text based software files the header contains all of the changes and modifications and sometimes the source control management tool will auto add comments for you.

By having a method to access the comments in the VI I could implement a similar feature with LabVIEW and our source control.

[vt92]

This is a good suggestion.  I hope it is implemented in some form or fashion soon.  For me, it is annoying that the comments move with the BD cleanup.

[dpga]

I use the labels of block diagram elements (loops, vis, functions, etc.) to comment on the code. This gives similar advantages to being able to comment on each line of a text based language.

[Darren]

Available in LabVIEW 2013