Best Practices Lite

“Best Practices” are methods or techniques that are accepted as superior to alternative ways, so we should expect anybody to adopt them. Surprisingly, we all dodge best practices – because they’re too complex, too much effort, or too (insert-other-excuse-here). But why not take small steps?

LabVIEW Dev Days 2017 - Best Practices Lite
LabVIEW Dev Days 2017 – Best Practices Lite

Software engineering is a comparably young, but never the less highly sophisticated and complex science. It comprises of an abundance of management disciplines and processes that all come with their own set of tools. The complexity of both the processes and the tools needed to adopt them can be frighteningly high. So, while anybody in their right mind will agree that best practices are the way to go, it happens quite often that there is no time and money invested into them.

Best Practices Lite?

It is actually a common habit to not adopt best practices at all. Especially with diverse teams of engineers who have expertise in other areas than software development. The perception of things like agile development, continuous integration or unit testing is one of high complexity. But while that’s mostly true, it should not be the reason or excuse to not take any action at all!

You can adopt an agile mindset without knowing the vocabulary. You can conduct informal code reviews, compile a handful of style guidelines, or play around with tools like VI Analyzer that are already out there, and see if it helps you or not.

Best Practices Lite!

If you live your life pragmatically (like I try to do), maybe the following three examples of “lite practices” might be of interest to you, or even motivate you to try something new.

Be as agile as you can

If you read the 12 principles behind the Agile Manifesto (agilemanifesto.org), and if you drop the fancy vocabulary, what you’re left with is plain common sense. Take the following four ideas as proof:

  1. Deliver working software frequently […]
    What good does it bring to try to deliver working software in short cycles, eg every other week? It helps with keeping the scope manageable, especially for inexperienced developers. Two weeks’ worth of LabVIEW coding are a tangible goal. By declaring yourself to delivering biweekly, you take a lot of pressure off yourself. You make it easier to stick to a fixed schedule and create good software, “one sprint at a time”.
  2. Welcome changing requirements, even late in development […]
    What are the reasons for changes in requirements? Requirements change if they were unclear or incomplete from the beginning. From experience, I’d say that both reasons apply most of the times.
  3. Working software is the primary measure of progress
    Especially as an external supplier, I’m used to being measured against my software. If it works, I can send the invoice. Simple like that. But even with an internal team, everybody has to report to someone in one way or another. Being able to show working software helps a lot with milestone acceptance tests.

Find a Common Coding Denominator

Coding conventions and style guides are nothing more than a set of definitions that recommend programming style, practices, and methods. They help improve readability and make software maintenance easier. Most programmers already apply coding conventions habitually. As soon as you start working in teams, it will make your life easier to write down some “rules”. Only after you write them down, everybody on the team knows about them and can start applying them.

Our coding conventions have grown over time and now cover topics such as language, style, conventions, documentation, framework-specific stuff, design, VI icon layout & colors, error handling and codes. But the first rule I jotted down was actually “background color of block diagram is grey” (don’t judge me).

If you need some help to get going, take a look at NI’s LabVIEW Style Checklist.

Don’t be shy, show your code

Why would anyone take the time to show his code to peers, or take a look at code of a fellow programmer? The two main reasons we see are improving code quality and sharing code knowledge. Both things happen implicitely: Showing code to someone else forces you to really look at your code and think about it. Quite often, you don’t even need anybody else’s input to find flaws or potentials for optimisation! Of course, code reviews serve the purpose of educating others who might need to support your code in the future. And last but not least, reviewing code is a way of sharing programming knowledge and techniques amongst the team.

Code reviews can be done very formally, but there’s no rule that says you cannot start by just showing your latest masterpiece to your co-worker! Grab a person, sit down, and fire away. Try to agree on a time frame beforehand, and try to stick to it (that might be hard, because of all the discussions). Look for value in feedback, even if your initial reaction may be disagreement. If you find that hard, read Humility and Better Programming by Brian Powell.

And if you assume the role of the reviewer, just try to focus on identifying real issues instead of cosmetics. Look for good things, and bring them up to the creator of the code. Review the code, not the creator!

Code Review Measure: WTFs per minute
Code Review Measure: WTFs per minute

These ideas were originally presented together with Julian Lange (Siemens AG) at NI Week 2017 in Austin, TX and again at the LabVIEW Dev Days 2017 in Nürnberg, Germany. If you want to know more, take a look at our presentation slides. You can download them from NI’s forum pages (http://bit.ly/NIWeek-2017-DigNRG) or from the Session Catalog (http://bit.ly/NIWeek2017-HVDC).

2 thoughts on “Best Practices Lite

  1. Joerg,
    Great article. We missed you at NIWeek.
    I wanted to address this point:
    “And if you assume the role of the reviewer, just try to focus on identifying real issues instead of cosmetics. Look for good things, and bring them up to the creator of the code. Review the code, not the creator!”

    This is very important. One way we have addressed this is by having a set of VI Analyzer tests that the developer needs to run and address before the code review. The first thing we do during the code review is to go over the VI Analyzer test results. VI Analyzer tests take care of the majority of the cosmetic issues. With the new feature in LabVIEW 2018, the developer can even add labels to ignore a VI Analyzer test result if it does not pertain to that section of the code (find out more at https://forums.ni.com/t5/VI-Analyzer-Enthusiasts/New-VI-Analyzer-Features-in-LabVIEW-2018/td-p/3800021).

    Also, it is important to remind everyone that it is our code, not just the developer’s code. This helps a little with developers who might take the review personally.

    One last thing for reviews to be effective, there needs to be a list of action items and a way to follow up on them. There is nothing more frustrating in a code review than finding the to-do items from last code review still there.

    Regards,
    Fab

    1. Fab, thanks for your input! Yes, yes, and yes 🙂

      Regarding VI Analyzer, we’re working on it, but we have yet to come up with a set of rules that really reflect what we want (that also depends on the customer, though). I think LV2018 will help, as ignoring tests on a per-VI basis will make things easier. I hope.

Leave a Reply

Your email address will not be published. Required fields are marked *