Commenting Code (in a condensed fashion)

[DanielChile]

Although I develop LabVIEW applications alone (not on a group) I always try to comment out the code as much as possible, including ideas for future development or improvements (refactoring).

Constanly I find myself reviewing code after several months and, as you may know, I appreciate a lot the notes I leaved to myself. (Have you seen "memento"?).

The only drawback is that (at least up to LV7.1) you end your diagram with a lot of "dead" areas occupied by comments, which leads to (even) greater diagrams where you have to scroll a lot (more).

I would like to see comments as little icons that when the mouse hovers over them show the complete text. Or maybe instead of an icon could be the first words of the comment plus "..." dots, I don't know.

What do you think?

Daniel R.

[Louis Manfredi]

Hi Daniel:

A couple of tricks, sort of achieve what you want:

1) Enclose the comment in a sequence structure frame, right click to turn off autogrow for the frame, shrink the frame so that only enough of the comment to serve as a label remains.

2) Write the comment in a String Constant, right click to turn on the vertical scroll bar, and shrink the Constant to fit your needs. (Or you can even make a string array constant-- for multiparagraph comments.)

3) Any block diagram constant can have a description which shows up in context sensitvie help.

Above are few traditional work-arounds for your problem. I think I agree, however, that some specific tools such as you suggest would be better, might even encourage better documentation practice for all of us.

I work alone too-- but still need the comments-- the notion that ANY programming language can be self documenting is a myth. When I come back to a LV program after a few months, it can be real cryptic what I was doing if I don't put in at least a few comments-- even though I try to write tidy code that is inherently readable. Also, there's always the chance the the client will ask you to explain how something works & its much more better if the code is somehow readable when you show it to them.

Best Regards, Louis

[Ton Plomp]

Hello Daniel,

an abvious? one would be a template VI with the discription with the info you edited. This would implement that for each comment you need another subVI...

Another thing could be a discription added to some data, so that if you hover the corresponding wire the info pops up.

both solutions give the data in the instant help window.

Ton

[Yair]

You might want to check out Xnodes in the scripting forum. I haven't had the chance to look into them, but they allow you to create executable code on the diagram and might be suitable for this (maybe create a folder of diagram documentation VIs for each project?).

And yes, I have seem Memento :thumbup: . I hope that's not how you document your code.

[lavezza]

What I have done in the past is put a free label where I want a comment, but only put in a number (1, 2, etc.). Below all my code I have a very large free label with a numbered list of comments. This allows the code to be fairly compact but still fully commented. It might not work for everyone, but it works for me.

Pat

[Jim Kring]

What I have done in the past is put a free label where I want a comment, but only put in a number (1, 2, etc.). Below all my code I have a very large free label with a numbered list of comments. This allows the code to be fairly compact but still fully commented. It might not work for everyone, but it works for me.

Pat

Hey, Pat: you look very familiar (). Have we met?

[Mike Ashe]

I have used the numbered free labels and also the string constant with scroll bar.

Another method is to pop up on loops or sequences and enter comments in their description about everything inside. Another method I am experimenting with is to leave the free labels, then have the VI link to a help topic in a *.chm file for the overview of the VI and then if I need detailed info I can look up the free label in the chm contents tree. There is a slightly more sophisticated version I'm hacking around with attempting to use scripting to do this cleanly, but it is not ready for prime time.

YMMV

[Yair]

Hey, Pat: you look very familiar (). Have we met?

Jim, since you didn't put any smilies there I'll assume your question is serious and respond by saying that if the birth date in Pat's is correct, that means that he was only 3 when the man in the picture (which I shall refer to as J.K.) founded NI. Does that help you recognize him? And just to be on the safe side - .

[DanielChile]

Hi everyone, thank you for your comments. They helped me think about what could be the best "workaround" (for me) on my wish. It's all about how everyone feels more comfortable.

At least for me, commenting out code must be as fast as possible. For example when writing a short comment on the diagram, is not the same to put a label (three tab hits to select text tool, one click to position on diagram, write and enter) that to put a string constant (one right click to make functions palette appear, move mouse over or click "string", click on string constant, click to position on diagram, write and enter) (4 steps versus 6 steps, 50% less). I might be exaggerating but for me these things make the difference between a well documented diagram versus a bad one.

Between suggestions you made I liked the most the description of a constant. However, I don't use the context help window very often, because I find it takes too much valuable screen space. So, instead of the constant description I suggest writing on its "tip strip". When using the "hand" tool and hovering over the constant will make the comments appear, almost as I wished on my first post. Is not as fast as inserting a label, but I find it good enough.

Thank you! :thumbup:

Daniel R.

[Yair]

At least for me, commenting out code must be as fast as possible. For example when writing a short comment on the diagram, is not the same to put a label (three tab hits to select text tool, one click to position on diagram, write and enter)...

This will probably not be a good suggestion for you, because it will require you to change the most basic way you work with LV.

I use the auto-tool selection. I know that many people feel it is always wrong, but personally I feel that it is almost always right and it makes it much easier to program (one hand only ).

Anyway, if you're using the auto-tool, double clicking on an empty area of the diagram or the FP (the trick is to find such an area) will create a free label which you can immediately start typing in - just double click and start writing.

[PJM_labview]

This will probably not be a good suggestion for you, because it will require you to change the most basic way you work with LV.

I use the auto-tool selection. I know that many people feel it is always wrong, but personally I feel that it is almost always right and it makes it much easier to program (one hand only ).

Anyway, if you're using the auto-tool, double clicking on an empty area of the diagram or the FP (the trick is to find such an area) will create a free label which you can immediately start typing in - just double click and start writing.

Or alternatively alway keep an empty (or with a space char.) free label sitting on your BD and just CTRL+Drag to make copy of it when needed. This should be very quick.

PJM

[Jim Kring]

Jim, since you didn't put any smilies there I'll assume your question is serious and respond by saying that if the birth date in Pat's is correct, that means that he was only 3 when the man in the picture (which I shall refer to as J.K.) founded NI. Does that help you recognize him? And just to be on the safe side - .

Assuming that any of my questions are serious is a huge mistake. And, if you think about it, there was a Smily in my post.

[Yair]

...a huge mistake.

AD withdrawl symptoms?

And, if you think about it, there was a Smily in my post.

Well, it was hard to see under the moustache.

[lavezza]

Hey, Pat: you look very familiar (). Have we met?

I see you've noticed my limited edition Jeff Kodosky halloween mask.

I will occasionally put it on and walk around the Mopac buildings shouting things like:

"Why the HELL is scripting taking longer to ship than undo!?!"

"Urs interupted my dinner again last night, would someone please work on the Mac version!"

"LabWindows! I wasn't serious, it was just a joke and James ran with it."

"Don't you ever mention Mathworks to me again!"

"Let's re-write it all in Lisp"

and, my favorite

"Greg McKaskle, put your damn pants back on!"

Pat

[crelf]

"Greg McKaskle, put your damn pants back on!"

Now there's an image I didn't need just before afternoon tea...

[JasonKing]

Now there's an image I didn't need just before afternoon tea...

You don't have to sit next to him every day! Is there some long-standing joke I'm unaware of that I should be giving him crap about?

[Jim Kring]

You don't have to sit next to him every day! Is there some long-standing joke I'm unaware of that I should be giving him crap about?

Even if there wasn't, now's a great time to start one

[crelf]

Even if there wasn't, now's a great time to start one

I allegedly heard an alleged rumor that he allegedly smells funny...

[Michael Aivaliotis]

OK, people let's get back on track.

This is actually a nice feature request. I think it would be very usefull. :thumbup:

Somehow to augment this would be the ability to add a comment which acts like a strict-type. For example, I am always wanting to add comments next to enums to list descriptions documentation about what each enum element does and how it ties-in to other processes in the application. If you use an enum for messaging commands then a small description list of each command next to the enum is very helpfull. It would be nice to copy this comment to the recipient VI that handles\parses the command enum. If later you decide to add a command\enum element then you edit the comment in one place and then all other copies of the comment would get updated.