A report of an issue should always contain three parts: how to reproduce it, what is being currently observed, and what is the expectation.
When a software engineer discusses a bug, usually what they mean is a fault or a defect. If we adopt the excellent definition offered in the book Practical Software Testing:
A fault (defect) is introduced into the software as the result of an error. It is an anomaly in the software that may cause it to behave incorrectly, and not according to its specification.
Paraphrasing it, a defect is simply a behavior deviation between the specification and the implementation. A good defect report therefore needs to have three parts: steps to reproduce it, the expected outcome, and the actual outcome.
The first part is important to give a proper context to the reader. The process to reproduce the defect needs to be described in a step-by-step fashion. Each step must be clear to everyone who is familiar with the product but not necessarily aware of the problem yet. The complete set of the described steps needs to be minimal, it should only contain the absolute minimum of steps to demonstrate the defect.
It is relatively straightforward to verify that the steps to reproduce the defect is non-ambiguous and minimal. Grab another person, perhaps a co-worker, and ask them to follow the steps. If that person does not need to ask a question or request a clarification, then the steps can be considered good.
When someone follows the steps described earlier, that person should observe an actual outcome. This is the result of the behavior of the current implementation. Since this report is about a defect, clearly the outcome is not what the reporter expects. Thus, it is mandatory to describe the expected outcome, the result of the behavior when the implementation follows the specification faithfully. Stated differently, once the defect is fixed, the observed outcome will match the expected one.
Let us pick an example, a defect in JavaScriptCore (the JavaScript engine used in WebKit) originally filed as WebKit bug #162013. Using the above framework, we can rework the defect report to look like the following.
Title: Duplicate parameter names with default parameters should throw a SyntaxError exception
A title should be a concise answer to the question, “What kind of problem do you have?”.
Steps to reproduce:
1. Launch WebKit Nightly
2. Open the console of Web Inspector
3. Run the following JavaScript code:function f(x=0, x){}
Any web developer should be able to follow the above instructions without any difficulties.
Actual: The test code is executed without any error.
Expected: A SyntaxError exception is thrown.
This contrast between actual vs expected emphasizes the difference between how JavaScriptCore currently runs the test code and how the specification treats the test code as syntactically invalid.
With this simple approach, anyone can understand a defect report without spending hours analyzing it.
As a final reminder, a good defect report should be as objective as possible. It should not contain any opinions, predictions, or guesses from the reporter. It is of course fine to comment on the report and share some subjective thoughts on the problem or the solution, but those need be clearly marked as such, separated from the undisputed facts discovered in the investigation.
Remember, don’t code today what you can’t debug tomorrow!