Random Ramblings on LabVIEW Design

Community Browser
Labels
cancel
Showing results for 
Search instead for 
Did you mean: 

Re: Commenting I Like!

swatts
Active Participant

Happy New Year Shapers of Clouds in the Air,

I'm back at the coalface with a mountain of work to do, presentations to create, Conferences to drive forward and a whole host of other stuff. Makes me tired to think about it, so instead I'll write an article.

 

Let's talk about documentation, the two extremes in the discussion about documentation go like this.

 

If you need to document your code, your code is difficult to understand.

VS

All code needs to be fully documented.

 

Most people are near the centre, my view is that you should ideally be able to understand the code without documentation. I also don't trust documentation to be up to date as it is rarely an active part of the project.

 

But there is some documentation I love.

 

Block Diagram Documentation

Here's some typical SSDC code and in this snippet there are 6 types of documentation I like.

Documentation I like A-FDocumentation I like A-F

 

A) Bookmarks are great, we use them for quick #TODO notices, tracking issue numbers and traceability for large changes.

B) Set LabVIEW to display constant label names, it improves the readability of the code at little cost.

C) I like the blue template comments that indicate bits of the template that can be modified. In this case adding new messages to be handled by the UDP receive loop.

D) Labelling case statement logic, improves readability and as a bonus improves logical design. This is because if you have to write the logic down, it becomes very clear if it is becoming complex.

E) We Number and label our loops, this is good for telephone support to guide people to the correct structure and similar to D) labelling your loops clarifies your design decisions.

F) Shift registers benefit from being labelled.

 

You'll also notice the preponderance of plain language in the code above, this is sometimes called self-documenting code. Use Enums, Strings and polymorphic selectors to add more information to your code.

 

Issue Tracking

Issue TrackingIssue Tracking

Something we're just starting to get value from is adding Issue Tracking comments, this improves traceability and is just plain helpful.

 

Finally we put a lot of information in our VI Description.

VI DescriptionVI Description

This tells us the version of the software the issue was fixed on.

 

I've a lot of research to do for my next presentation "Modular Design Deep Dive".

Will talk more about GDevCon soon too.

Lots of Love

Steve

 

Steve


Opportunity to learn from experienced developers / entrepeneurs (Fab,Joerg and Brian amongst them):
DSH Pragmatic Software Development Workshop


Random Ramblings Index
My Profile

Comments
joerg.hampel
Active Participant

As always, spot on!

 

In addition to setting LabVIEW to display constant labels, we also set it to display subdiagram labels by default:

sub-diagram labels.png

 

We also created a VI Analyzer test to check the presence and values of subdiagram labels:

vi-an.png

 


DSH Pragmatic Software Development Workshops (Fab, Steve, Brian and me)
Release Automation Tools for LabVIEW (CI/CD integration with LabVIEW)
DQMH® (The Future of Team-Based LabVIEW Development)

FabiolaDelaCueva
Active Participant

Great reminder Steve!

 

I have been told that I tend to put too much documentation on my diagrams. I feel that it is easier to remove the labels if they are on your way (and them put them back! 😉 ) than to add the developer's intention to the block diagram later. Specially months later or when that developer is no longer with the team.

... I just thought of an idea for a Quick Drop shortcut that hides all the labels and then via undo, puts them back... I will think more about that... 

 

We have created a free label for #Code_Review_To_Do with its own color. Then created a Quick Drop shortcut to add them to block diagrams. This ensures everyone has spelled the bookmark the same, it is really quick to add them during a code review and due to their color, they are easy to spot.

 

Another advantage to labeling your structures is that tools like the Unit Test Framework, will refer to your structures by name. For example when they report coverage. 

 

One documentation that I didn't see mentioned in your excellent post is the primitive labels. A lot of developers don't know that a LabVIEW primitive label can be edited. I have used this to document quick conversions. For example changing the label of the multiply function to say "converting to ms". 

 

Thanks,

Fab 

For an opportunity to learn from experienced developers / entrepeneurs (Steve, Joerg, and Brian amongst them):
Check out DSH Pragmatic Software Development Workshop!

DQMH Lead Architect * DQMH Trusted Advisor * Certified LabVIEW Architect * Certified LabVIEW Embedded Developer * Certified Professional Instructor * LabVIEW Champion * Code Janitor

Have you been nice to future you?
joerg.hampel
Active Participant

Seems like I can't edit comments, so here's another one with the download link to the VI Analyzer test checking for subdiagram labels, in case anybody wants to give it a try:

 

https://www.dropbox.com/s/n2njwn1ik6pzulk/hse_subdiagram_labels_v0.3.11.zip?dl=0

 

(what's the preferred way to share files here? is dropbox ok?)


DSH Pragmatic Software Development Workshops (Fab, Steve, Brian and me)
Release Automation Tools for LabVIEW (CI/CD integration with LabVIEW)
DQMH® (The Future of Team-Based LabVIEW Development)

swatts
Active Participant

The great thing about blogging is that the article is finished/improved by the comments.

@Joerg that's a great suggestion!

@Fab That's a brilliant idea, love having a quick drop comment, it means that it's both standardised and helpful.

Steve


Opportunity to learn from experienced developers / entrepeneurs (Fab,Joerg and Brian amongst them):
DSH Pragmatic Software Development Workshop


Random Ramblings Index
My Profile

crossrulz
Knight of NI

joerg.hampel,

Something like this should probably submitted to the VI Analyzer Enthusiasts group.  You could make sure this is not a duplicate of something else that was submitted.  But share the link to whatever you post.


GCentral
There are only two ways to tell somebody thanks: Kudos and Marked Solutions
Unofficial Forum Rules and Guidelines
"Not that we are sufficient in ourselves to claim anything as coming from us, but our sufficiency is from God" - 2 Corinthians 3:5
joerg.hampel
Active Participant

crossrulz, 

 

thank you for pointing that out. Of course, you're right! I added the test to the list, you can now find it here:

 

https://forums.ni.com/t5/VI-Analyzer-Enthusiasts/Test-Subdiagram-Labels/ta-p/3739097

 

 


DSH Pragmatic Software Development Workshops (Fab, Steve, Brian and me)
Release Automation Tools for LabVIEW (CI/CD integration with LabVIEW)
DQMH® (The Future of Team-Based LabVIEW Development)