Five Tips for Writing Good Bug Reports

Chad Scates

We normally take the humble bug report for granted, but getting your company to write good bug reports is one of the cheapest and easiest ways you can increase product quality and shorten development schedules. That’s because, when a bug report is poorly worded or doesn’t include all the key information, it takes a lot longer to find and fix the problem being reported—and often it doesn’t get fixed at all.

Now, the precise guidelines for reporting defects vary by company and product. The information you need to include in a problem report for an Android app is very different from that needed for an in-police-car video recorder. And the way problems are reported varies too: Sometimes you’ll be filling out a detailed form as a part of your team’s formal defect tracking system, and other times you might be sending a quick email to a development manager.

But in all cases certain general guidelines apply.

So, help out your development team and increase the odds that the problem you saw will be addressed by following these five easy steps to writing good bug reports!

  • Report every defect you see. Don’t assume someone else has reported the problem unless you know there’s already a bug filed for it. Two days after we released a product, I once talked to a very angry sales guy at my company, who was irate that my team hadn’t addressed a problem he was seeing all the time. It turns out there was something special about his environment and he was the only person who had seen the problem in the pre-release code. But he didn’t file a bug report—he figured the QA team was responsible for that.
  • Write a clear problem report. Please answer these three basic questions: What did you do? What happened? What did you expect to happen instead? (And don’t be cute: Writing that the application “bit the dust” is not particularly useful even if it makes you feel better. Did it crash? Hang? Display a fatal error message?)
  • Tell us about the environment. Often the environmental details matter: What build of the code are you using? What are the versions of the other key software components in the system? (This will be domain specific, but for instance I normally want to know the version of the device firmware, or the operating system, or the web browser; whatever is relevant to the product at hand.) If you’re hitting server APIs, is your client pointing at the production environment or a pre-release staging environment? And so on.
  • Gather any log files. Again, this varies by product, but normally there is quite a lot of information that might be useful for debugging in a log file or core file, especially when we’re talking about pre-release products. So if possible, please save these diagnostic files aside as soon as you see the bug. The product I’m working on right now only keeps a two-hour long log file, because of storage space constraints. So if you forget to include the log file and then my team has to ask for it, it’s probably too late!
  • See if you can reproduce the problem. After the problem happens once, save aside the log file, and then, if possible, push the car back up to the top of the hill and see if you can make it happen again. The bugs that are easiest to zap are the ones where the developer has a very clear path to reproducing the problem. I realize this isn’t always possible—especially if you’re in the middle of demonstrating some pre-release product to an important customer—but when it is possible, it can be tremendously useful.

Do you have any other hints? Pass them on in the comments!

Cardinal Peak
Learn more about our Audio & Video capabilities.

Dive deeper into our IoT portfolio

Take a look at the clients we have helped.

We’re always looking for top talent, check out our current openings. 

Contact Us

Please fill out the contact form below and our engineering services team will be in touch soon.

We rely on Cardinal Peak for their ability to bolster our patent licensing efforts with in-depth technical guidance. They have deep expertise and they’re easy to work with.
Diego deGarrido Sr. Manager, LSI
Cardinal Peak has a strong technology portfolio that has complemented our own expertise well. They are communicative, drive toward results quickly, and understand the appropriate level of documentation it takes to effectively convey their work. In…
Jason Damori Director of Engineering, Biamp Systems
We asked Cardinal Peak to take ownership for an important subsystem, and they completed a very high quality deliverable on time.
Matt Cowan Chief Scientific Officer, RealD
Cardinal Peak’s personnel worked side-by-side with our own engineers and engineers from other companies on several of our key projects. The Cardinal Peak staff has consistently provided a level of professionalism and technical expertise that we…
Sherisse Hawkins VP Software Development, Time Warner Cable
Cardinal Peak was a natural choice for us. They were able to develop a high-quality product, based in part on open source, and in part on intellectual property they had already developed, all for a very effective price.
Bruce Webber VP Engineering, VBrick
We completely trust Cardinal Peak to advise us on technology strategy, as well as to implement it. They are a dependable partner that ultimately makes us more competitive in the marketplace.
Brian Brown President and CEO, Decatur Electronics
The Cardinal Peak team started quickly and delivered high-quality results, and they worked really well with our own engineering team.
Charles Corbalis VP Engineering, RGB Networks
We found Cardinal Peak’s team to be very knowledgeable about embedded video delivery systems. Their ability to deliver working solutions on time—combined with excellent project management skills—helped bring success not only to the product…
Ralph Schmitt VP, Product Marketing and Engineering, Kustom Signals
Cardinal Peak has provided deep technical insights, and they’ve allowed us to complete some really hard projects quickly. We are big fans of their team.
Scott Garlington VP Engineering, xG Technology
We’ve used Cardinal Peak on several projects. They have a very capable engineering team. They’re a great resource.
Greg Read Senior Program Manager, Symmetricom
Cardinal Peak has proven to be a trusted and flexible partner who has helped Harmonic to deliver reliably on our commitments to our own customers. The team at Cardinal Peak was responsive to our needs and delivered high quality results.
Alex Derecho VP Professional Services, Harmonic
Yonder Music was an excellent collaboration with Cardinal Peak. Combining our experience with the music industry and target music market, with Cardinal Peak’s technical expertise, the product has made the mobile experience of Yonder as powerful as…
Adam Kidron founder and CEO, Yonder Music
The Cardinal Peak team played an invaluable role in helping us get our first Internet of Things product to market quickly. They were up to speed in no time and provided all of the technical expertise we lacked. They interfaced seamlessly with our i…
Kevin Leadford Vice President of Innovation, Acuity Brands Lighting
We asked Cardinal Peak to help us address a number of open items related to programming our systems in production. Their engineers have a wealth of experience in IoT and embedded fields, and they helped us quickly and diligently. I’d definitely…
Ryan Margoles Founder and CTO, notion