Among the other choice profanities we throw at our PC, the more technically minded may describe the program as “buggy”, a label for poor performing software. So how do we stop buggy software from being released into the world? Sadly, it’s impossible, or at least prohibitively expensive, to have 100% bug-free code. However, we can reduce the number of wee beasties that get released into the wild through good software development practices, like code reviews and testing. Key to all of this is talking about the problems with your product, and documenting what is going wrong (as you may a therapist...). As a product development consultancy, the i4pd team have a great deal of experience with spotting and resolving bugs. Here are some of our top tips to help you talk about your bug problem.

Bugs tend to be logged in some form of list. This can be as simple as a making a text file or spreadsheet on your PC, or via dedicated software to manage these items on the cloud (you may have heard your software team talking about Jira, github, Azure DevOps or other tools in this context).

A mix of emails, slack channels, and teams chats reporting bugs makes it difficult to go back and find the relevant information about a bug. That’s not to say these tools aren’t useful for discussing problems, but a single source that contains all the reported bugs cuts down on admin time that can be spent solving the problem.

The development team could be looking at a long list of bugs and don’t want to drill down into the detail of each issue to work out what it is about. A good title can help set the context when they first approach the problem and can help with sifting through the data when looking for the entry.

Now a good title can help to identify the bug in the list, but we still need to know what the problem is: a single sentence doesn’t give the detail required for an investigation. A short, vague description like “The lights don’t work” doesn’t help us fix the issue.

What we need is information on how to recreate the problem as the person fixing the problem may not be the person who reported it. If the fixer can recreate the problem then they can work on ways to approach it, narrowing down the potential causes of the issue before implementing a solution. If the fixer cannot replicate the issue their chances of removing the bug are slim.

A good template for recreating a fault is “Action -> Expected result -> Actual result”. For example, “Holding the power button for 3 seconds when the device is in operation should cause the white LED to flash 3 times and then the device should shut down. In testing, holding the power button causes the blue LED to come and the device remains on.” You can also add some additional information which may be relevant to the problem, such as “when the blue LED came on the Bluetooth connection between the device and a phone dropped and then reconnected”. In this case, the additional information is useful as it would point to a problem with the button handling protocol in the device confusing a power down sequence with a Bluetooth connection activity. This all helps the software developers narrow down where to look in the source code.

Although detail is useful for the development team, too much can make it difficult to work out what the issue is and how to recreate the . For most commercial products, giving the full atmospheric conditions when the fault occurred isn’t necessary.

Only add one issue at a time, this helps keep the focus of the log and also stops any issues getting prematurely closed because it was added to an entry that got fixed. For example, instead of logging "The lights don't work and the switch is inverted" in one entry, split it into two items, one about the lights and the other about the switch.

Along with warning about being too specific, don’t put guesses about the source of a bug into the initial report. The report should say what the issue is. A good issue logging tool should allow for adding comments to the report. A comments section is a good location for thoughts on solutions. However, recreating the fault and performing further testing should be done before making claims about the bug source, unless you are very familiar with the product or have experienced a similar problem on a different project.

Everyone wants to ship high-quality products, but not all problems are created equal. Our embedded software engineers classify issues with a severity rating ranging from critical (this causes the product to not work) to a wish (it would be nice if…). This helps us get to the most important issues first, ensuring the product is robust, but also allows us to think about those extra features that make a product go from earliest sellable product, to earliest lovable product.

As with most things in product development, the best way to fix bugs is to talk about them in a sensible manner. At i4pd, our embedded software team have the systems and expertise in place to create robust products and stop the bugs in their tracks!