Tuesday, 28 October 2008

Code that's good enough...

[caption id="" align="alignleft" width="300" caption="Photo by The Wandering Angel"]Photo by The Wandering Angel[/caption]

Let's face it, there can be a huge temptation to keep polishing and honing your code almost indefinitely, to get it "Just Right".  This is good because it shows you care about making your code work really well; caring and taking pride in one's work leads to producing really great code.  However, there is such a thing as to much of a good thing.  To strike a balance and to make sure that you don't just go on tinkering for ever, it's important to have some understanding of when your code is "good enough".  This can mean a number of different things, depending on the context, and all of them are important to at least some degree.

...for the task
Number one on the list:  is your code good enough to do the task it was designed for?  If not, then your project isn't finished yet!  If you've been following our advice, then you have a list of objectives for your software project.  Go down the list and check in turn whether your code meets each of them.  If it does, then your code is good enough for the task.  If not, then you have more work to do.  So get to it!

It's important to not get sidetracked here.  There will be things that your code doesn't do, maybe things that you think will be really important.  If they're not on your list of objectives right now, then save them for later (perhaps version 2.0).  It's generally more important to get a solid version 1.0 completed that meets the core objectives, so that you and/or the other users can start using the software to do some science.

...for the user
Code is good enough for the user when it does what they need in a reasonably straightforward way and in a reasonable amount of time, where "reasonable" is defined by the relevant context.  Typically, you might want the code to be usable by another scientist who is unfamiliar with the code and perhaps even the intricacies of the method it implements.  Many users would love a black box that they can trust to do the right thing - try to give them this, as much as possible.

A "reasonable" amount of time can vary a lot from case to case.  When analysing a big data-set, it may be the case that a run-time of hours, day or even (in some cases) weeks is okay.  Here, you need to do the analysis once or at most a few times and then you'll have your answer.  On the other hand, your software might be used in exploring new data as they're generated, in which case it might be very annoying to the user to have to wait more than a few seconds.  Generally, "reasonable" will be obvious to you as you'll be familiar with the context; and if you're not sure, talk to some of your potential users and see what they say.

Remember that often in science, the user is actually you. So why not take the time to ensure that your code is straightforward to use and isn't going to cause you headaches when you're trying to actually get some science done.   You'll thank yourself...

...for peace-of-mind
This means the peace-of-mind of you, your users and anyone who will rely on the results generated by your software.  Everyone using your code need to feel comfortable that your code is doing what it's supposed to do.  Do you really want your latest and greatest scientific results to be critically reliant on some code that you're not 100% confident in?  Or even worse, do you want people using your code to be announcing important new science when you've got a nagging doubt as to whether it really gives the right result?  We didn't think so.  If you're still unsure, try to understand why and then find a way to test it.

This means that you must have tested the code sufficiently (and in enough different ways) that you can prove to everyone, including yourself, that your code really does work.  Do this right and do this right now, then you won't have to worry about it at a later date.

...for personal satisfaction
You should feel proud of your efforts.  You've earned it.  You've worked hard, met all your objectives and done it with highly crafted, well-written code.  So take the time to make sure you're genuinely proud of your shiny new code, that you've finished off all the last little bits, perhaps made the GUI a bit more visually appealing, perhaps done a last bit of refactoring and commenting.  Don't spend too much time on this, but it's a nice feeling to hand over a project knowing you've done a really great job.  Note that there can often be pressure to finish quickly and get onto the next thing, but try to manage expectations (of your boss, your collaborators or whomever) enough to buy yourself this bit of time.  It's well worth the effort.

And if all of the above are true, your code is good enough.  So stop.

No comments:

Post a Comment