More decorations for commenting code

[Daklu]

"A picture is worth a thousand words..."

That's especially true when describing complex interactions of the kind often seen in code.  Currently the block diagram decorations consists of 4 elements: a line, a straight arrow, a frame, and a label.  I can and often do create state diagrams out of those elements, but they look very hacked together (i.e. unprofessional) and are cumbersome to create.  The alternative is to use an external graphics program and paste the image into the block diagram.  I do that sometimes too, but it makes it harder to keep the diagram up to date.

I'd like to see elements added to the decorations palette to help us create graphical comments.  Since state machines are very commonly implemented in Labview, that seems like a good place to start.  How about adding a state decoration and a transition decoration?  The state decoration should allow more formatting flexibility than the label does.  (Like having the first line centered and the rest left justified.)  The transition decoration should be an arrow that allows routing--either smooth curves or point turns.  It should also have a label attached to it for identifying the transition trigger.

Here's an example of a state diagram for some proof of concept code I wrote that I pasted to the block diagram.  I'd like to be able to easily do these kinds of drawings without needing a 3rd party app.

[labview4steve]

This one is so obvious it seems that no one has mentioned it....I for one support this 100%!

[vitoi]

I've had to do the same myself. I've done a flowchart in Microsoft Visio and then I've copy-and-pasted it into the VI (helps me write the code if it's right there and helps whoever maintains the code).

Would be so much nicer if it was part of LabVIEW's features. Kudos.

[JB]

Good idea. But, even better : bring back the State Diagram Editor which will document the code by itself.

[PaulG.]

Why don't we just put a good set of UML components in decorations? That shouldn't be too difficult.

[Daklu]

JB, I've never used the SDE so I can't comment on that, but from what I read on that thread the SDE creates a link between the state diagram and the implementation.  I don't want that.  I'm looking for ways to express ideas better, not something to create code for me.  There are many ways to implement a state diagram; I don't want the documentation to require a specific kind of implementation.

PaulG, I actually did consider that, but it raises all sorts of other issues.  UML is a defined language with specific rules.  Should the decorations enforce those rules, or should they allow users to do things that violate the rules?  All of the UML tools I've tried have frustrated me at some point.  They enforce the UML in an attempt to be helpful, so they didn't allow me to express the idea I was trying to communicate.  Often I can't figure out how to express the idea in a way that doesn't violate the UML and I end up with inadequate documentation.  I do use UML(ish), but I don't want to become a UML expert just to figure out how to document my code.

It also raises the question of is the block diagram really the best place to keep all UML documentation?  Intuitively I'd say no.  If you have a lot of UML diagrams it's probably better to keep them centralized in a separate file rather than distributed throughout the application.  On top of that having lots of UML documentation on the block diagram forces one to scroll around trying to find the information you're looking for.

Finally, implementing a complete set of UML components will take a lot more time than adding two decorations to the palette.  More dev time = less chance of it getting implemented.  The most bang for the buck seems to be with state diagram elements.

I'm not opposed to adding other UML elements to the decorations palette, but I didn't ask for it because of these concerns.  I figured I'd start small and see how useful it is before requesting additional R&D time to expand the idea.

[kegghead]

> It also raises the question of is the block diagram really the best place to keep all UML documentation?  Intuitively I'd say no.

I agree completely. It's also pretty common for my source code to come with several third party files that I use to create what are boil down to comments in the block diagram. I don't expect LabVIEW to have full equation editing capability for example, so I might have text files riding alongside a class or library with TeX code used to create equations which get pasted into the block diagram. Same thing for images etc.

I'd like to see better deocrations, but I don't think we need NI to make a half-baked image editor, equation editor, UML editor, or some other widget editor-- there are very good applications which specialize in these domains and the block diagram can accomidate any image that these third party tools could generate.

-kegg (mje@lava)

[Intaris]

Would hyperlinks in text comments not help soklve these kinds of problems?

I also agree that external documentation is best left externally (and in the Project).  But knowing what relates to what can be hard.

Just after posting, another thought hit me.  The ability to create hyperlinks to other project items would be useful.  Not embedded, just links.

[Daklu]

Would hyperlinks in text comments not help soklve these kinds of problems?

IMO hyperlinks solve a different problem.  Hyperlinks direct other developers to external information about the code.  Viewing and editing that information requires them to have the correct 3rd party application installed.  That isn't always true.  (This happens a lot any time code is shared with the community.)

Built in decorations allow developers to view and update the information without needing a 3rd party app.  The target use case is relatively simple apps or components that don't need extensive documentation, but will benefit from one or two diagrams.

I can see state diagrams and maybe class diagrams (since the class hierarchy window is a pain to work with and only provide inheritance info) being useful, but if you need sequence diagrams to explain your code I think external documentation is going to be better.  I haven't thought about any diagrams beyond those three.

[elset191]

FYI: Hyperlinks in Comments.

[Manzolli]

It would be nice to have much more, separated in classes (sub-palettes), with anchor points and some customization.

Separated: having more would make the decorations a bit confuse. The shapes can be classified as curves, arrows, round, squares, UML, classic and other.

Anchor points: anchor points in the middle of the edges and corners would be helpful.

Customization: instead of having many slightly different basic shapes, some customization would help reducing the number of similar ones. Properties that can be configurable: radius of a rectangle with rounded corner, width of the edge line, shadow on/off and width, etc.