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.
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-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.
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.
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".