Systems Blog

Five Ways to Minimise Miscommunication Bugs
Franco Civello Wednesday 13th June

All software contains some defects - it’s a fact of life. However, as an analyst, I find software bugs annoying, but not all for the same reasons. The first annoying category is bugs that could have been prevented at the analysis stage. These normally arise from an incomplete or incorrect interpretation on my part of the business or system requirements, so my professional pride gets hurt.

There is a second category of bugs that I find unsettling because they could have been avoided by better communication. These are the ones where code behaves differently from specifications and models produced by analysts. I was once again reminded of how irritating this can be when I discovered the reason behind a bug that was raised a few days back. I don’t want to bore you with the gory details - in essence it came down to overreliance, by the developer, on a specific example I had included in the specification document and supporting model. The specification and model were correct, and so was the example, but I think the developer read the example and made an assumption about the general case, which in effect implemented a rule that the specification did not include.

This is just an example of bad communication. Doubly ironic because the example was included to improve communication, as specifications can be hard to read when they deal with general rules and have no examples.

So what is to be done to try and avoid this kind of ‘miscommunication’ bug? Here are five ways of dealing with it, each with its advantages and disadvantages.

	Advantages	Disadvantages
Improve communication by involving developers in producing/reviewing specs/models.	Developers become more familiar with the system/requirements and many bugs are avoided altogether, before code is written.	Developers need to take time out of developing and work alongside the analyst, often on next iteration’s requirements.
Use code walkthroughs involving both the developer and the analyst. Ask developers to show how their code meets the spec.	Analysts can spot functional errors before they become bugs. Developers are more motivated to read the specs.	Time taken to do walkthroughs. Analyst must be able to read code.
Improve day-to-day communication with developers and testers to see where they may be going wrong.	Fewer errors due to misinterpretations of specs.	Time taken by analyst to take part in current iteration’s development and test activities. Analyst must always be close to rest of team.
Do away with formal specs and models, avoiding the mismatch in the first place. Rely on oral communication and informal sketches.	Most developers love this as they become more in touch with the problem domain. Teams can be more productive. Analysts can put more effort into communicating and supporting the team.	Code and test cases become the only formal documentation, so changes can be more expensive and less predictable. It is easier to lose control of the process.
Do away with (most) code, producing executable models that can be executed directly on the underlying platform. Examples: Mendix, Wavemaker, OutSystems.	Solutions are self-documenting and can be produced by both developers and analysts. Productivity goes up.	Platform maturity and acceptance. Most developers hate this as they have to learn to use non-standard platforms and they feel their hard earned technical skills in JEE or .Net are devalued.

At RDF, we strive to follow the first two practices in projects which adhere to our UP-based development process. The Unified Process is a risk driven iterative process, in which code is written and tested against precise specs and UML models. See my recent technical papers for more details.

Scrum projects use practices three and four. However, despite not having precise specs and models, we use acceptance criteria to test user stories, so code can fail these and miscommunication bugs raised. Reviews and walkthroughs are still useful to catch problems in complex areas before testing.

We have also built two systems in Mendix and found that the model/application is self-documenting, so the miscommunication bug never really occur in this type of project.

As a general rule, getting things right more often involves spending more time in conversations, reviews and workshops. No such thing as a free lunch, once again.