Re : Re: auto creation of flow diagrams

[altenbach]

---

@nistudent wrote:
surely that is rubbish, labview follows a data flow, if you label your variables in a manner which makes the task obvious then surely it is possible to generate a tool that allows the automatic generation of a flow diagram at least for each of the loops in the program, hence saving me the annoying and time wasting task of documenting all this code, which shouldnt have to be part of the job.

---

So you're saying that documenting code is not the programmers job??? That is a very interesting statement. You might as well say that Einstein should not have bothered publishing his theory of relativity, but just scrawl E=mc² on a subway tunnel! 😮

"Annoying" and "time wasting" are some pretty strong words! Maybe programming is not something you should be doing for the rest of your life then. Programming is always a big waste of time. You spend maybe 5% on the creative and fun part (algorithm developement), then waste the remaining 95% on UI usability, debugging, debugging some more, adding features, documentation, debugging again, fixing bugs discovered by customers, revise documentation, etc. It is all part of the job!  And IF you look at it right, all these steps can be fun. (and with LabVIEW, they typically are!) 🙂

A well written program des not really have "variables" per se, so I am not sure what you mean by the first sentence. In LabVIEW, the wire is the variable. You have controls and indicators (Which should be named descriptively, especially if you turn them into connectors) that tap into them and retain their own data copies, as well as local variables which are simply secondary access points to front panel objects. Of course we also have now shared variables, which is again more a communication tool between independent code segements.

For documentation, It is more important to modularize your code into blocks labeled with something that describes the function. If you use descriptive names for your subVIs, you're almost there. ;).

[LV_Pro]

  I'm going to  jump into the discussion, as one who has had to both figure out a lot of code written by others, in a variety of "style" and techniques, and frequently tasked with documenting this code. As Mike stated, flow charts, as such, are not very useful in trying to describe complex programs. As to how easy it might be for a charting program to document the flow of a program, it wouldn't for most LabVIEW programs, other than some very basic, written linearly (think flat sequence structure) ones. While LabVIEW has been called a "data flow language" I would propose that it has evolved past that. While parts of a program will still be subject to data flow, with vi's not executing until all of their inputs have received data from "upstream", it really doesn't describe some of the structures that those may be parts of. Flow charting a multi-sourced queue based program would be non trivial. As to a documentation program understanding the flow, well I've seen some really bad code, with stuff flowing all over the place with locals, globals, etc. Charting it would have resulted in something that would look like those pictures of the webs of spiders given LSD.
   While Mike might have been a little strident in his response ("after all, he's not a tame Lion"), it sometimes is our job to do annoying tasks, annoying because they are so much more difficult and time consuming when done after the fact, particularly when you weren't the original programmer and you are having to figure out what and why the original programmer did what ever they did, and whether it was the correct thing to do. As the principal in a small consulting firm, I have to do this all the time, frequently with code that was written by very inexperienced engineers, and it isn't fun. But it sometimes it is the job.  If you can find, or write, a program to do what you suggest, a lot of programmers would be interested. As to how easy, well National Instruments took a long time to come out with their VI Analyzer tool, which basically checks the code for stylistic issues, which allows a pretty definable set of rules.  Given the almost limitless techniques employed in writing a complex LabVIEW program the real answer is, modularity (break up functions into smaller, more understandable functions) and documentation at development time. The first allows the description to be pretty high level for the main part of the program, and then the individual parts can be more easily described, well, individually. The later is pretty critical, as sometimes the original author may have a hard time remembering why a piece is coded a certain way (then again, it may just be me, there is a reason I use a "trilobyte" icon). As Altenbach said, 5% creative, fun stuff, 95% the rest of the task.

Message Edited by LV_Pro on 07-04-2007 04:25 PM

[rolfk]

---

@nistudent wrote:
surely that is rubbish, labview follows a data flow, if you label your variables in a manner which makes the task obvious then surely it is possible to generate a tool that allows the automatic generation of a flow diagram at least for each of the loops in the program, hence saving me the annoying and time wasting task of documenting all this code, which shouldnt have to be part of the job.

---

One thing that has not been mentioned well so far. IMO documentation of software especially software written in LabVIEW should not even attempt to document the actual code, which in the case of LabVIEW is already graphical, just in another way to fill a few more hundred pages when printed out. The opposite is true! It should give a concise overview of what the software does globally without bothering about every single loop, LabVIEW primitive etc. All an automated tool could do is recreate the exact details as are already present in the LabVIEW diagram in yet another graphical way and in such a way fill probably several 100 pages with some sort of clueless graphics that are easily implemented in a single screen LabVIEW diagram (a modest UI state machine for instance). Except wasting paper it won't do any good for anyone since nobody will bother to look at such an idiotic thing as looking at the LabVIEW diagram will be a lot more straigthforward anyway.

This of course does assume that you took some care to follow at least a minimal style guide in some way. Maybe a different documentation after the fact could be helpful if you created a program that consists of many stacked sequences, countless globals and locals and a diagram that you have to scroll over 10 screens to see what it does, but such a diagram can't possibly be analyzed by an automated tool intelligently after the fact and if you still would attempt that, such a tool would either have to give up at some point (if it is smart enough) or create a documentation that would be even worse to read than the original diagram. So there you are again with manually creating such documentation after the fact and in fact spending that time instead to clean up the code and make it more readable might be much better spend time IMO.

Program documentation should IMO rather give a very global picture of the entire application structure, and in many cases can also go on a different documentation level into detail by documenting a particular algorithme or something but it should not be yet another way to say exactly the same that the LabVIEW diagram already does, and here is where the automated tools simply can't help since they only can stupidly translate but not comprehend what the code does.

Rolf Kalbermatter

Message Edited by rolfk on 07-05-2007 10:16 AM

[Odd_Modem]

I know this might sound silly, but after you give your boss the flow diagram is the boss going to ask for proof that it is correct?

[mikeporter]

Excellent points Rolf. You bring up the idea that documentation should have a point and that point is helping other people (or even yourself - let's not forget that) understand how and why the code does what it does. In the past there have been people who have proposed structures like, "Every line of code shall be documented" which in variably led to things like:

printline();    \\print a blank line

or whatever the LV equivalent of that would be. The rule of thumb I use is that in general I don't try to explain how LV works and I don't describe things that are obvious if you simply read the code. You need to expend the ink on explaining the things that might not be immediately obvious. For example I have a technique for doing limit checking on an entire array of values at once even if there is a different limit for each value. This technique depends heavily on the way LV propagates and responds to the floating point value "NaN" and the way it works is certainly not "immediately obvious" - so I document the heck out of that.

Which sort of leads to the next point you made, which is that how extensive documentation needs to be is to some extent a function of the readability of the code. Good code can be read more and so needs less documentation, bad code is less readable and so needs more documentation.

Mike...

[TiTou]

---

mikeporter a écrit:
In the past there have been people who have proposed structures like, "Every line of code shall be documented" which in variably led to things like:

printline();    \\print a blank line

---

Hmmm... I think we have to make the distinction between :
A . the documentation inside the code
   and
B . the paper documentation that describes  how the application works.

 A . is developer oriented and should describe core functions that might not be obvious, includes VI documentation and icon in the properties so that the developer doesn't necessarily need to open the VI to know what it does.

 B . should, IMHO, exit is 2 different levels :
    B1. user oriented and explain the main functions of the application and how it should be used
    B2. developer oriented, but at a higher level than A. and should be include B1 plus a state diagram, a data flow diagram and a description of how parameters are handled. The purpose of B2. is to help the developer estimate how much work will require a new functions asked by the customer.

I totally agree that the up-cited sentence "Every line of code shall be documented", is purposeless in a text based code, but it doesn't not really apply to LabVIEW... I guess the "good translation" into LabVIEW would be, "Every VI shall have a VI documentation and an descriptive name and icon".
I also agree with Rolf, reversing the development process doesn't make sense. NIStudent, maybe you should consider using the "state diagram toolkit", it helps you drawing your architecture, then make a screen shot of the state diagram and go develop.

[Andrew Boniface]

On Jun 29, 7:10 am, NIStudent <x@no.email> wrote:
> Basically I have written all the LabVIEW code and it is all working fine, I have now being given the task of writing the flow diagram to go with it so that someone else can understand the code. I am currently using Microsoft Visio and was just hopeing NI might have a far better tool that could auto generate my diagrams.
> &nbsp;
> &nbsp;

This won't autogenerate, but LabVIEW itself will permit drawing the
diagrams you want, if you can imagine the diagram you want as LabVIEW
source code. The main limitation you have here is your diagram must
follow the LabVIEW convention of inputs on left, outputs on right.
Most symbols one would want to use must be written as LabVIEW VI's.
Since thay are only printed, not run, the internal logic of these
"symbolic VI's" is not relevant, but the inputs and outputs should be
forced to the appropriate datatype. On the other hand, the icon
bitmap is far more important than in actual LabVIEW programming,
likewise the layout of the inputa and outputs.

It may be possible to write high level VI's which serve the purpose of
documentation, and at the same time function as runnable code, but
this approach limits one to producing diagrams which are absolutely
literal. Sometimes the diagram of greatest explanatory value is not
perfectly literal.

This is especially true when one desires a high-level diagram, which,
for the sake of simplicity suppresses details.

[AustinPeter]

Ok, we're getting somewhere. I like the feedback I am getting. Just to clarify a few points

A) I have been asked to produce documentation of my code so that it can be programed in a different language, (embedded C). my labview code is fully documented to sytle guideline etc, but obviously this isnt much use to someone who has never seen labVIEW before. so it is far more the paper format I am talking about.

B) by variables i meant controls, (and indicators) ie each "local variable" is a refering to the original control. By naming them something of use ie. "motor speed" then it would be pretty obvious what was happening at the point where you write "20" to "motor speed" in an automated documenter. The way I have written my VISIO diagram is to have an intial page with all the controls on them and every time they are read or written to i have a reference to that control. now i appreciate this makes data flow for linear flow diagrams a tad dificult but it is the same when reading a piece of labview code and determining the flow and if any race conditions are occuring.

I have broken down every case into a flow diagram and every subVI in the case into a sub VI. I dont have any globals etc and am using a standard state machine format.

surely there is a standard out there that people use to document labview code for other programmers in a different language, and if yes surely there must be a way to automate it so that we dont have to spend 95% of our time doing the "non-interesting" and highly time consumeing side of our jobs as by the sound of it we'd all be alot happier. Lion tamers and all.

ps. I like the vi heirachy idea as a simple overview.

[mikeporter]

I see what you are getting at, but there is still a basic misunderstanding of the development process. Creating embedded C code that models the LV code you have developed is simply not going to work very well. Every programming language is different and so requires a different way of thinking about problem solving. The C design needs to come from the same place the LV design did - the statement of the functional requirements for the system.

Now having said that, you might be able to use the LV implementation of the functional requirement to help you identify capabilities and functions that you need in the C implementation, but trying to make the C look like the LV is going to get ugly.

To see what I mean let's say metaphorically that the goal is to drive 3000 mile from coast-to-coast here in the US. Now let's say that you have made the trip before in a Rolls-Royce so you know it will do the job. But it would be nonsense to say all motor vehicles that are wanting to travel long distances need to look like a Rolls-Royce. Still looking at the Rolls' structure will give use some hints of things we will need for any implementation. For example, tires will be helpful - though the exact number might be up for negotiation and range from 2 to 16.

Mike...

[tst]

Other than the fact that you are abusing locals as variables (they should normally only be used to update control values or in quick and dirty apps), you're also ignoring the fact that there can be many ways in which a piece of code can be written and that an automated tool can not be taught just one of them. You say you're using a standard state machine format, but there is no such thing. There are common formats and there are templates provided by NI, but there is no standard.

In the same way, there is no standard for documenting LV code. There are numerous options like:

• A requirements document \ system description.
• Module documentation (UML, etc.)
• Specific algorithm descriptions (text, flowcharts, etc.).
• Text documentation in the code and printing the code.

For what it's worth, I don't think there is usually any real point in documenting LV code for other languages. When you write code, you're supposed to use it, not to go and rewrite it in another language which may have a completely different paradigm. If you do want to rewrite, you usually take the design documents which were written before the code and you might use the code as an additional resource.

What you do usually document for other languages are interfaces. For example, if you were going to export LV functions in a DLL, then you would document the interface so that it could be called from other languages, but not the internal document. An example of this would be when I interact with an external DLL - I am given the documentation of the interface, but I have absolutely no idea what the code looks like.