Filing good bugs

Every developer has to deal with them. Whether they are coming from your users, you are on the filing end for a bug in an OSS project or filing something against the tools you are using, bug reports are a part of developer life.

I was at Apple when this meme went viral. While it is firmly tongue in cheek this meme does highlight the importance of reporting bugs and issues in a manor that is consistent and open to all.

I’m not going to talk about the quality of Apple’s bug reporting tools. Saying that the quality of radar is why you don’t file bugs is just an excuse for not helping the community. And a poor one at that.

One of the many things I learned in my tenure at Apple was the importance of good and frequent bug reporting. Here are a few tips that will help improve the quality of your bugs.

Clear steps to reproduce

Which is better:

Dont know what little black bin icon means?


Steps to Reproduce:

*1) add item to basket **2) to to checkout **3) enter valid registration and shipping/billing address **4) go to order summary **5) check gift message box **6) enter text into message field **7) dismiss keyboard and go to another part of the view *8) come back to the gift message box and tap in it again. see that all text you had previously entered is cleared

Obviously these are a bit contrived (though they are actual bug reports I’ve received on a recent project). It’s obvious which is preferable, but it does illustrate the issue. Be explicit as to how you were able to replicate the issue. Even if you have screenshots or videos of the actual issue happening provide the steps you used to replicate the issue. Often when trying to replicate the bug so that you can get the steps, you’ll find other information that could be potentially valuable.

Screenshots / videos

A picture is worth a thousand words


And showing me what you saw when you filed the bug is far more valuable than trying to explain it in text. And if you’re an iOS developer and you don’t know how to do screen videos of your device with Quicktime in Yosemite then you are massively missing out. (It was a life changing feature for iOS testers!).

On Android the process for screen recording has a few different options of varying degrees of complexity. If you have Android Studio screen recording is built in. If you don’t then you’re going to have to jump into the command line to make your videos. I’ve also had some devs point to Android Tool for mac as a good resource as well.

Skitch by Evernote (available for Android and iOS) is a great tool for annotating screenshots directly on your device or on your computer.

Logs / crash reports

These are the bread and butter of reporting a crash. In my early days I had filed many bug reports detailing crashes and one of the first things the bug screener would come back and ask me for were the crash logs. These are invaluable to developers. Even if your crash is easy to replicate, the crash log can let the dev know exactly where to start looking. It can also help group seemingly unrelated bugs together. A stack trace from two different crashes in two different areas can lead back to a single point of failure and save the screener or the dev time in trying to replicate the issue and trace it back.

While never perfect, there are a number of tools out there to automatically report back to you when an app crashes in the hands of a user. Crashlytics, or now, is a popular one put together by the people at Twitter that services both iOS and Andriod. HockeyApp, now owned by Microsoft is another. There are many reviews out there covering the many options in this arena. Read up, and pick one that works best for your workflow.

One issue per report

After payment has been verified - app crashes (using a iphone 4s, not sure if its the phone or the app?). Also when entering card details it says mm/yy - please specify if you need expiry or valid from date. Also CVC - perhaps entering a phrase or a question mark and hover over saying three digit security code at signature strip on back may be helpful. When going through categories, movement is a little bouncy and will not scroll through properly.

Where do you even start?! This may seem obvious to some but to many it’s not. Be concise. Be focused. Have a point. Submit only one issue per bug report.

Never assign blame

Bugs were not introduced into the app just to frustrate you. The developer who introduced or missed the bug is going to be more frustrated and upset that it shipped than you are. Be professional. Be empathetic. Be helpful. Don’t make it personal.

Bug reports are not the place for you to air your personal grievances about the state of the software or the world in general. That’s what Twitter is for . Seriously, have some empathy when filing bugs. Odds are you have been on the receiving end and know what it feels like. So remember that and file the types of bugs you would like to see yourself.


The real purpose of bug reports are to be helpful. They are to solve a problem and to make things better.

And always remember the first bug report and the woman responsible for giving us the term. Thank you Rear Admiral Grace Murray Hopper!