Flat sequence and stacked sequence

[muks]

---

Where do you put a long comment that would not fit on one screen beside the code ?

1. I don't comment the code
   
2. Outside the visible part of the screen
   
3. In a sub-VI
4. In the description of an element of the diagram
   
5. In the description of the VI
   
6. I use a state machine
7. I use a flat sequence (should not be mentionned because it won't solve the problem of case 2)
   
8. I use a stacked sequence
9. ...
   

   ---

   Oh Wow Frankly 8 seems to be the best option.

Do i follow it...

noooooooooooooo

honestly 1 is what i do

[corys]

I like to put a sub-vi with a big question mark for its icon on the BD. Open it up, and it's just a front panel with text boxes of my documentation.

[tst]

JB wrote:

And what is faster ?

• one click on the stacked sequence selector to switch from the code to the comment and back
  
• move the horizontal scrollbar to read the comment and then reajust its position to show the code

---

Ctrl+Scroll on the SSS.

Personally, I don't tend to have very long comments either. I do have comments which contain quite a bit of text, but no more than a two or three short paragraphs usually.

Incidentally, a better way of handling versioning of a VI is to use source code control.

[Graziano]

---

@JB wrote:
Please take notice that neither of my examples lead to use variables of any type ! I spoke about rare circumstances !

---

Okay, that's not for coding that you use stacked sequences... okay!

graziano

[Graziano]

---

@tst wrote:

Personally, I don't tend to have very long comments either. I do have comments which contain quite a bit of text, but no more than a two or three short paragraphs usually.

Incidentally, a better way of handling versioning of a VI is to use source code control.

---

That's near to XP programming: almost no comment at all, the code has to "comment by itself".

graziano

[JB]

---

Graziano a écrit:

Okay, that's not for coding that you use stacked sequences... okay!

graziano

---

No, the stacked sequences help me to respect an even greater commandment (IMHO) which states that a diagram must be limited to the screen size !

[Graziano]

---

@JB wrote:

No, the stacked sequences help me to respect an even greater commandment (IMHO) which states that a diagram must be limited to the screen size !

---

That's a great commandment, I agree  ! Even if many times I dont respect it

graziano

[tst]

---

Graziano wrote:

That's near to XP programming: almost no comment at all, the code has to "comment by itself".

---

Not at all. I actually comment quite a lot. I find it much easier and quicker to read what a piece of code does than to start deciphering the code. The comments themselves don't have to be very long for that to happen. The trick is keeping the comments up to date if the code changes.

And yes, I also happen to think that SSS and diagrams larger than a single screen are legitimate in certain circumstances.

[Graziano]

A good way for commenting can be a SubVI which has a descriptive icon, possibly with some text, and an intuitive name.  It's the same as naming functions the best way to describe their behavior, which in most cases avoid comments! Of course, this holds in some cases, not always!

graziano

[tst]

That's not exactly commenting. SubVIs should definitely have good names and icons and their description filled in (although that doesn't always happen either), but I'm refering to textual comments in the diagram itself. No matter how good your code is, it will almost always be simpler to read a short piece of text describing what happens, because in the comment you don't usually go into all the details.