Bug reporting is a critical part of the communication around a code-based project. While we hope to catch issues with our testing before deploying new code, the fact is that some bugs will inevitably slip through. As a result, having a feedback system for users to report bugs is important for the continuous improvement of code-based systems.
However, communicating about bugs can be challenging. A successful bug reporting system goes beyond tools to convey the bugs (such as issue tracking on GitHub or Jira tickets) and even beyond having templates for bug reporters to fill in to standardize and improve the quality of bug reports. Improving our communication skills is also essential to an effective bug reporting system.
There are a number of wonderful books and guides to effective communication within the tech world, and I would refer readers to those sources for comprehensive discussions of the topics. This post is meant to narrowly focus on a specific bug communication issue I’ve noticed in my career: use of the words “wrong” and “fix.”
What is a bug?
There are many definitions of a bug, but for the purposes of this article a bug is “code” that causes a “program” to produce an unexpected result or unintended behavior. The words “code” and “program” can refer to a lot of things, such as a traditional programming language (e.g. Python) and scripts written in that language, or they can refer to Excel formulas and a template made from them.
What is the goal of a bug report?
The aim when writing a bug report is to get the bug addressed quickly. As Cem Kaner puts it, “The best tester [or user] is the one who gets the most bugs fixed.” Well-communicated-about bugs are quicker for developers to identify and remove. Regardless of the format of the bug report, the quality of the communication plays a large role in the timeliness of bug removal.
Why is a bug’s result not wrong?
The code (or Excel formula) that was written does exactly what the human developer told it to do. Tracing the implications of that statement, data that comes out of a program is always exactly as the developer made it. If that output is not consistent with the project requirements, that issue can be called a bug, but not “wrong” output. If there were no project requirements, or if the “unexpected” behavior actually was a project requirement, then there’s no bug, but rather the user might want to request a change to behavior or a new feature (again, nothing was “wrong”).
This is about more than word choice – it’s a distinction between the concepts/meaning of
- 1) output of a program vs. expectations and
- 2) truth vs. falsehood.
Semantics aside, what’s wrong with wrong?
Words like “wrong” and “fix” are not informative or productive. Even putting aside the semantic point about use of the word “wrong” in this case, saying that something is wrong isn’t terribly informative. As the developer, my next two questions would always have to be “What specifically is wrong?” and “In what way is it wrong?” While asking and answering these questions doesn’t seem to hinder the process on the surface, in practice the delay between questions and responses can delay the bug-fixing process by hours or even days.
Additionally, use of the words “wrong” and “fix” can lead to feelings of discouragement or anger in the developer. Now, for those of you reading this thinking that this is fluffy emotional garbage, keep in mind that upset people tend not to do their best work. If a developer is discouraged, that might slow down how quickly they’re able to fix a bug. If they’re angry, they might not feel motivated to prioritize your bug in the scope of all their other work.
So what words SHOULD I use?
One strategy that I’ve found to be effective is to frame discussions relative to your expectations. “I expected result X, but observed the result Y.” This type of phrasing is accurate, concise, informative, and unlikely to hurt anyone’s feelings.
Secondly, try asking questions. Instead of saying “this isn’t what it’s supposed to be,” try asking “how did you come up with your result?”. This approach not only stops from offending the other person, it can also reveal flaws in logic that could otherwise be overlooked.
Regardless of your word choice, remember: you’re all on the same team
Developers and users all want products to be of high quality and delivered on time. In the midst of results that don’t match expectations or even delayed deliverables it can be easy to grow frustrated with your teammates, but never forget that everyone is trying their best. If everyone always keeps that in mind, and uses that understanding to fuel their communication, we can all live happier and more productive work lives.
