Author Topic: How to report bugs - A Coder's Perspective  (Read 61457 times)

0 Members and 1 Guest are viewing this topic.

Offline karajorma

  • King Louie - Jungle VIP
  • Administrator
  • 214
    • Karajorma's Freespace FAQ
How to report bugs - A Coder's Perspective
I have been meaning to write one of these for ages. By now most of you should be aware that you should use Mantis to report bugs. However most of the bugs I see reported on Mantis either shouldn't be there or require lots of interaction before the coder can actually get down to fixing the bug. The result is bugs that take ages to fix or sit in Mantis for months unlooked at. So I'm going to write a guide on how I fix bugs. The other coders might have other habits or ways of doing things but a lot of this should be applicable to all of us.

I tend to visit Mantis a lot more often than I actually code to fix bugs because I have to see if any new bugs have appeared or if anyone has posted feedback on an old bug. But when I am in the mood to code I'll go to Mantis to figure out which one I should look at today. This is the main reason your bug should be in Mantis and not on the forums. If it isn't I'll probably have forgotten about it between responding to your post and actually being in the mood to code and fix bugs.

That doesn't mean every problem should go in Mantis. Not every crash is a bug. Many are caused by incorrect drivers, installation or simply doing something in a mod you really shouldn't be doing. Unless you're certain it's a bug you probably should try to work through the problem on the support forum first. Not only is this less annoying for me than a mantis report it's also faster, I only check Mantis every couple of days but I check HLP every day.

Having bugs in the correct category is important. I tend to ignore graphics bugs in favour of FRED and Multiplayer ones. Other coders do the reverse. If your bug is in the wrong pile it can wait for ages before someone notices. Having a good description in the title helps a lot. I'll pay more attention to problems with bits of FRED or multiplayer I already know since I'll suspect that I can fix them more easily than coders who don't know that area of the code. There's also the chance that I introduced the bug. I always find that embarrassing and any bugs I may have created get bumped up to the top of my priority list.

Once I've found a bug I like the look of I'll read the report itself. The easier the bug looks to fix the more likely I am to fix it right there and then. The bigger or more complex bugs tend to wait for a day when I think to myself "I'm gonna fix x today." So make it easy for me. If you have a mission bug that you can get to happen in your mission at the 5 minute mark I'm less likely to fix it than if you've made the effort to make a test mission where all I have to do is press a key to get the bug. The less ships, explosions and other gunk there is in the mission the easier it is to fix as I have less possible causes.

A bug with a good test mission bumps the priority of the bug up several notches for me. Of course there are cases when you can't make one but if you can, and you don't leave it up to me to make one then that increases the speed the bug gets fixed at. When possible try to make it so that a key press triggers the bug. As that way I can run through the mission with and without the bug and see what the difference is if need be.

If you can't make a test mission a good Steps to Replicate entry is a good idea. If a bug report says that a bug happens often and I can't get it to work after a couple of tries I'll go off and try something else instead. If the bug produces an error make sure you get it down in the bug report. The error is a vital clue to what is the cause of the bug (Especially in the case of assertions) and the almost always give me a good starting point to look.

If you have to describe the bug a picture might be a better idea as it gives me a much more immediate picture of what's wrong. A bad description might result in me looking at the wrong part of the game/code. 

If your bug is with a mod and you expect me to test it run a debug build and fix any errors that pop up first. Expecting me to click through a bunch of warnings and assertions before I get to the problem is unlikely to keep me working on the problem. It simply makes it much more likely I'll give up and come back to it later. This is especially true if the errors or warnings are fixable and in the same area as the bug. In fact I'm unlikely to even touch a bug in that case as it could be that whatever the warnings are about is the cause of the bug.

If I need additional information to solve the bug I'll post on the comments section of the report. This is where it becomes important that you check your mail. Respond while I still remember the code I looked at the night before and I'll probably go back and look again. Respond 3-4 months later and I probably won't look at the bug for ages simply because I don't fancy relearning everything I knew about that particular part of the code again. Especially if I suspect I may need to ask for yet more information. Not responding at all usually results in a bug being marked "Unable to reproduce" followed by closure of the bug.

Once I've identified what I think is the problem I may post a test build. If you don't test the problem I'll assume the problem is fixed and close the bug. I'm less likely to come back to it again if it turned out the fix didn't work as now I have to relearn what the original code did as well as my fix.

I think that's enough for now. Hopefully I'll see some better Mantis reports as a result of this. :D
« Last Edit: January 25, 2008, 02:56:23 am by karajorma »
Karajorma's Freespace FAQ. It's almost like asking me yourself.

[ Diaspora ] - [ Seeds Of Rebellion ] - [ Mind Games ]


Offline Fabian

  • AI Code Modulator
    Temporal Mechanic
  • 25
Re: How to report bugs - A Coder's Perspective
Very nice view.

Yes, that is how bug fixing does work.


(Probably forgot one 'R')

How about making this a sticky thread?