Tuesday, 26 May 2009

The 4 levels of making code work

[caption id="" align="alignleft" width="300" caption="Photo by dbking"]Photo by dbking[/caption]

You want to make your code work.  Anything else would be dumb, right?  Right.  But as we've discussed before, deciding whether your code is good enough to count as "working" isn't always straightforward.  On way of looking at this is to categorise four stages of relative completion of a software project.  Any one of these four can count as "good enough" if that's what your project requires and in many ways they represent a sequence of levels of technological development.

Make it work...

The first stage is to make the code work.  Obviously, this is a minimum requirement for any project (!).  You're not looking for an optimum solution at this stage, just one that works.  This could be a prototype; you've proved the idea, but in the most hacky way possible.  It could also be a version 1.0 where you've taken care to write well-crafted code, but you've implemented simple methods that aren't at all optimised.  The point here is that your code does the right thing.

Make it work well...
Once your code works, you can consider improving how well it works.  This can mean a number of things.  Most obviously, it can mean optimising your code to run faster and/or using less memory.  It could be improving usability, perhaps by changing the GUI or the input file format.  It can also mean refactoring the code so that it's tighter and more easy to work with, so that future changes are easier for you to make.  Or perhaps your code produces numerical results that are accurate to 1% (which is acceptable, given the requirements), but by using an improved algorithm you can reduce this to 0.1%.

In some cases, the version your write after a prototype could live in this category, depending on how advanced it is.  If you've prototyped extensively and learned better ways of implementing the solutions you need, your code might quickly end up in this category.

Often there are vast numbers of tweaks you can make that would could as "making your code better".  Try to stick to the ones that make a significant difference, and leave out the ones whose impact will likely be negligible.

Make it work automatically...
This stage is one that's a lot less often visited than the previous two.  Once you have code that's working well, the next logical step may be to start to automate some (or all) of the functionality of that code.  The reason for this is to save the user (and to some degree the programmer) from having to think about that functionality - they can just trust that it happens.  This then frees them to spend their time and effort concentrating on other things.  For example, consider how email works.  Knowledge of where and how to physically route an email must exist in the system, but nowadays you don't need to know anything about this; all you need is a single address.  This is the result of automation in the system.

Care must be taken with automation.  The ideal situation is one where the correct choice/inputs/courses of action can be determined unambiguously.  Automation is a lot harder when uncertain decision-making is involved.  And of course, the objectives of your project have to be amenable to being automated.   Usually a command-line tool rather than a GUI tool (although it is easy to write one program with both interfaces) it is worth bearing this in mind from the beginning rather than trying to retrofit it in later (it's a pain extracting command-line functionality out of a GUI tool, much easier to put a GUI on top of a command-line tool).

A mantra we've encountered is "do, redo and then automate".  First make it work, secondly do the work again locally on your machine with the same parameters the automated process will use, thirdly deploy the automated process and test the result (and fix the inevitable bugs!).

Make it work invisibly...
At this point, the code is tested, trusted and part of a large pipeline, project or structure. The code is solid, mature and used by other projects. It might be open-sourced at this point and there maybe several other maintainers and, hopefully, an active community of user and developers.  By this point it is part of the background, something that just works and people take for granted (and are extremely surprised if there are any bugs or problems!).

Congratulations! You have written something that people rely on just like water, electricity and Google :-)

In conclusion
"Good enough" is a programming concept that varies a lot from project to project, but overall it broadly fits into four categories.  Understand which one you're aiming for and whether it might be useful to try to progress your code to a higher level of "Good enough".


  1. [...] nice blog post for levels of making code work was brought to my attention. Here is a quick reminder [...]

  2. [...] Not: Yazının orjinali için tıklayınız [...]

  3. [...] The 4 levels of making code work (Programming for Scientists) [...]

  4. This is a great site for everyone interested in programming.Keep the good work up!