Posts in category development - page 6

Anatomy of a good bug report

Working on the .NET Framework was an interesting but often difficult time, especially when dealing with vague or incomprehensible bug reports.

Look before you file

Head to Bing, Google, official support sites and bug database if you have access to it (Microsoft Connect, Bugzilla for Firefox etc.) to see if others have run into this issue. Searching for the error message can yield good results but remove elements of the message specific to your project (e.g. class names, property names etc.)

The reasons for this are:

  • you may have made a mistake (likely if the software has seen considerable use)
  • behave differently to your expectations (the dreaded ‘by design’)
  • already be fixed (in the next release and possibly as a patch)
  • have an acceptable workaround (why accept a workaround?)

If you are running into problems with developer tools, also check out:

Consider how likely it is that you’ve discovered a bug given the complexity of what you are doing, how unusual it is and how mature the software is. Attempting something simple on an established piece of software likely means you’ve made a mistake or misunderstood the documentation.

A good bug report

So you decided to go ahead and report the bug (we all need better software after all).

The essence of a good bug report is having just the right amount of information to identify the bug without unnecessary detail.

Let’s break it down.

What happened

The most important element is describing what happened, and there are four major possibilities.

Error message

You told the software to do something, and it displayed an error message instead.

On a good day, the error message lets you know why it can’t do what you asked and lets you know what to do to make it work. Given you’re filing a bug report, it isn’t one of those days.

The error message is likely cryptic, doesn’t tell you how to get what you want or is just plain wrong. We’ll need that message in its entirety so:

  • Copy Windows message box contents as text by pressing control-c when it’s in focus
  • When there is a lot of text take a screen print (Print Screen on Windows, CmdShift3 on Mac OS X)
  • Localized error messages may slow down support responses – switch the app back to their language first


When a piece of a program (called a method or function) can’t do what it claims, it throws an ‘exception’ back up to the piece that asked (called) it. This exception is like an error message but with enough technical detail that travels back up the program until something deals with it (known as a catch).

When you see an exception, then nothing wanted to deal with it.

You see an error message that contains the exception and possibly a list of program pieces that couldn’t deal with it. This is a stack trace, invaluable to the person investigating your report, so include it.

Developers seeing exceptions in their program need to determine if they should be catching that exception or whether it shouldn’t be occurring. Feel free to trim the stack trace to remove your methods if you need to.

Unexpected behaviour

The software should have done what you wanted but did something you didn’t expect instead.

Report what you thought should happen, what the software did instead, how this is different and the reason why you think it should be that way.

Other people may not agree with your change, and in the case of shared programming libraries or frameworks, a fix for you can become a break for others that rely on existing behaviour.


The software just vanished from the screen without a trace. Crashed, terminated or unexpectedly quit and perhaps took some of your work with it :(

If you’re really unlucky, the software that crashed is your operating system. This could mean a blue screen of death (BSOD) on Windows, the grey screen on Mac OS X.

Often there are logs left behind that you can examine to identify what went wrong.

On Mac OS X, fire up Console from Application > Utilities and see what you can find. The iPhone, iPod and iPad do this quite often, and iTunes offers to send detailed information to Apple, who may share it with the application developer if it’s not their own.

Windows users should head to the Event Viewer and find the error and any additional messages that appear to relate to it and include these.

Steps to reproduce

Ideally, this is the minimum number of steps to reproduce the error every time. You want this to be as reliable as possible as companies have limited resources and won’t spend days trying to reproduce a low-impact bug.

This repro is a critical step in understanding the scope of the problem and its impact. If you can’t reproduce it in a few steps, there’s always the possibility you’re overlooking some other aspect that could be causing the problem – unexpected data or rogue code elsewhere!

For an application, this may be a data file or manual steps a user must manually perform via the user interface.

For a framework; a small self-contained project with just enough code to reproduce the failing scenario.


Bugs are often sensitive to their environment, and you should always include the version number of the software you are using as well as pertinent platform details,  including:

  • What operating system, version & service pack
  • What processor architecture (x86, x64, IA-64)
  • What language & locale your machine is running in (e.g. US English (en-US), Brazil Portuguese (pr-BR))

In the specific case of Visual Studio and .NET bugs:

  • What version of Visual Studio you are using (including any service packs)
  • What processor architecture you are compiling for
  • What language and compiler version you are using (e.g. C# compiling for 4.0)

You may need to include details for your desktop or developer machine and details of the server it is connecting to if any are involved.

What you’ve tried

Chances are you tried several things before filing a bug report. Let us know if you tried:

  • Alternate routes through the user interface
  • Entering data in a different format or order
  • A different computer or environment

Letting them know this means they can avoid suggesting things you’ve already tried or waste time trying them too.


How did I get started in software development?

Ken Egozi tagged me with the latest meme and this time it’s at least relevant :)

How old were you when you first started in programming?

Some time between 10 and 12 when my father bought home a ZX Spectrum and I ended up delving into the excellent programming manual when I finally ran out of games to play. At the same time my school opened up the computer room at lunchtimes…

What was your first programming language?

BASIC on the Sinclair Spectrum (evenings) and BBC Micro (lunch-times and after school). Multi-platform from the outset ;-)

What was the first real program you wrote?

Probably the MultiFile +3 disk & file management tool for the Spectrum in a mix of assembler and BASIC but I was also creating menu and copy protection for the BBC Micro around the same time.

I also trashed an expensive 3” disk drive at the time with a small bug in my end-of-disk detection code that resulted in the drive trying to step itself beyond the end several times and knocked it out of alignment.

What languages have you used since you started programming?

Well I’ve *used* the following although ones in italics for only brief periods involving one or two small applications.

  • BASICs: Sinclair, BBC, Microsoft, QBASIC, Mallard, QuickBasic, ASIC
  • Assemblers: Z80, 6502, 8051
  • Visual Basic, VBA, VBScript, VB.NET
  • C, C++, Objective-C, C#, Java, JavaScript, ActionScript
  • Turbo Pascal, Delphi, SQL, PHP
  • COBOL, RPG, SmallTalk, Algol, Prolog

I’m not sure if XSLT/XPath or RegEx’s count.

What was your first professional programming gig?

Writing IBM AS/400 (iSeries) banking applications in COBOL age 17 joining a team where the leader was already known as the Kindergarten Cop as everyone in his team was “only 23-25”. I got to delve into the kernel, general ledger and securities systems eventually single-handedly developing intricate multi-base-currency support leaving days before my 19th birthday. (Okay, a little pride there ;-)

If you knew then what you know now, would you have started programming?

Without a shadow of a doubt.

If there is one thing you learned along the way that you would tell new developers, what would it be?

Enjoy the journey, new languages are going to come and go so learn them just-in-time ;-)

It’s a shame computers and languages are more complex now but with the Internet and great books available there is no real barrier to entry.

What’s the most fun you’ve ever had programming?

Any application that brings a smile to a users face :)

Some ‘interesting’ moments have been revisiting school-level physics for a pool game and an on-the-fly domain class construction system for an international configurable payroll package.

Who am I calling out?

I’m not sure any of them are reading my blog any more but you never know ;-)


Ten commandments for developers

In order that applications and operating systems shall not drive users insane, thou shall:

1. Allow immediate termination

I hit the wrong button. I changed my mind. I didn’t know it would take this long.

Either way, the operation needs a cancel button that causes immediate effect and quickly clean up what it can.

If it was copying or uploading a file, delete what was done. For database operations, rollback the transaction. Formatting a disk leave it half formatted and un-format the first sector but do it FAST.

If you think the consequences are too great, ask what effect forceful termination or switching off the power is going to be like in comparison.

2. Leave start-up alone

I’ll do that right now; just let me log in… Zzz… Sorry. It should be done in a minute. Sigh.

Your app might be the centre of your world developing day and night – it’s not the centre of mine.

I might use it for several hours a day if you’re lucky. That doesn’t mean I want it starting automatically unasked.

It also doesn’t mean you can install services, background tasks or other junk that prevents me from doing what I need when I’m in a hurry and running with a low battery.

If you need to check for updates, do it silently in the background when I launch the app or add something to the Windows scheduler. Don’t create an entire service.

3. Not modify existing file associations

I tried that last time, and it screwed up my associations. I’m not going to try the new version no matter what.

I might want all video files to go through your app. I might not.

Let me make that choice and reverse it. If I uninstall your program, reverse it automatically and clean up the registry.

Associating every media file on my system with your app isn’t going to wow me. It isn’t going to make the sale or make me believe my system can’t live without your software.

There may be incompatibilities. Features you don’t support or perhaps a clunky UI, and I’ll uninstall your app to go back to my old favourite.

When all my associations break, you can’t bet I won’t be coming back to see what you’ve done in version 2.

4. Not ask inappropriate questions

Do you want to move or copy files from this zone? Yes or No.

Zone? What? Err, copy please. What do you mean, Yes or No?

I just performed a non-destructive operation, and you want me to confirm it?

Do you want to remember your password?

An insanely stupid question that appears after a login box doesn’t have a password stored, either because:

  • I don’t use the feature but can’t switch it off (never ask me again)
  • I’m not on my own computer (shut up for 30 minutes)
  • I have a new machine and haven’t typed it for months (ask me in 10 seconds when I find out if it’s right)

You rarely get useful options, but at least Firefox 3 realizes it should ask quietly at the top of the page after you can see if it worked.

5. Keep noise to a minimum

Windows has installed updates! AVG Anti-Virus updated successfully.

Business-as-normal – I DON’T CARE.

If there is a problem updating, let me know – unless it’s something simple that goes away without my involvement in a day or so.

People don’t call or message me day in and out to tell me nothing, neither should my computer.

This also goes for audio notification of trivial activities.

Don’t annoy people in their offices and homes with stupid noises just because somebody on the other side of the world has logged in.

6. Stay focused on the goal

The instant messaging crown was taken from ICQ because they overloaded the client with games and junk. People wanted simple messaging, but by the time they figured this out and delivered ICQ Lite, it was too late.

REAL repeated the same blunder where a good video player expanded to consume all available files, starting messaging me and breaking every commandment there is.

Adobe believes Acrobat should be more than a quick PDF viewer for physical page reproduction. They built a piggyback mechanism for a whole document management system. People don’t want their web browser locking up for 20 seconds while they load plug-in’s they’ll never use.

7. Make actions obvious and reversible

I don’t want a dialogue box with some sob story about why your app can’t do what I just asked or three paragraphs of text I have to scan for negatives, digest and mentally figure out what Yes and No will actually do.

Even worse is prompting a slightly different message with the same Yes and No options sending the user to the button they normally hit for a totally different message with potentially disastrous results.

If Yes is doing to delete the file label the button Delete. Dialogs in OS X do this, and you can answer them lightning fast with accurate results.

Better yet, just do it, put some text in the status bar, update the UI and learn how to write an undo mechanism.

8. Avoid restarts

If your application absolutely has to install a service, start it yourself.

If common files you are installing might be in use, check them or, better yet, put them in your own application folder.

9. Make configurations count

Adding options to your application is a choice to a certain point. Beyond that, it causes people to be unable to find the option they are looking for, becoming bewildered at the choices available before quickly heading to the close button instead.

If you absolutely must have extra options that only a small percentage of the population care about, just store them in the configuration system and forget about giving it presence on the user interface.

10. Adhere to the platform

Read user interface guidelines and only deviate when you know better than the expert team behind them. If you have to explain it, then you didn’t know better after all.

If the operating system has conventions for files, configuration and help, use them. Don’t claim that being the same across platforms is more important – people who use more than one platform know and expect them to be different already.

If you want to use an update, notification, or other commodity services, find what is already popular and a good fit and use that, don’t develop something different.


More screen-shots of Envy Code R preview #7

Work on my Envy Code R programming font has resumed and I’ve spent hours playing with the hinting process to ensure it looks good at sizes above and below 10 point:

Screen-shot of Envy Code R PR7 without smoothing on WindowsScreenshot of Envy Code R PR7 with standard smoothing on WindowsScreenshot of Envy Code R PR7 with ClearType on Windows

These look great – even more so when you consider there are no embedded bitmaps and very few delta hints.

There is still a lot of work to do – all the foreign characters, symbols and box-drawing characters (another 600 glyphs) require hinting and I should test it on the Mac, Java and Flash font rendering engines to make sure there are no show-stoppers there.

Preview 7 will consist of of just a plain style regular and bold because I need to get this out – it’s been too long since the last release. Preview 8 will add back italics and the Visual Studio italics-as-bold hack shortly afterwards.

Check out Talios’s shots using Java/Linux and Eddy Young’s shots in NetBeans.

A newer version of Envy Code R is available.