[/caption]In this post, we will look at the process of writing good code. There are a lot of aspects to this and we expect we'll be writing quite a few articles on various of them. We'll start with some basic rules for writing good code and also the sort of mindset you should try to adopt when writing code.
As with any kind of writing, there are some rules (or at least, rules-of-thumb) that it’s advantageous to adhere to when writing code. First and foremost, your code should be easy to read and understand. There’s no advantage in having arcane, obfuscated computer code; you, or someone else, might have to revisit this code a year after it was first written, by which time you won’t have any memory of what it is and how it works. Make life easier for your future self, or your future colleague.
"Pretty layout"
You should also have good layout at both the micro- and macro- level. Indent your braces to the same level, line up equals signs, anything that makes the code easier to read and understand. There is no computational downside to doing this, and it makes your life that much easier. A good rule of thumb is that if you’re not finding it more-or-less effortless to read your own code, you’ve not written it nicely enough.
Use sensible names
You should always give things meaningful names. Don’t call your variables “a” and “aa”, call them “lengthInMetres” and “massInKilos”. Don’t call your function “fptsce”, call it “FindPointSource”. Nowadays, there is no reason to not have informative names for things! The one exception (these are rules-of-thumb after all) is loop variables. It's ok to use "i" or "x" or whatever makes sense, as it makes the code more readable and everybody uses them. But, in general, variable and function names should explain what the variable/function is for and/or what it does. Well laid out code with good variable and function names is essentially self-documenting as anybody who reads the code later doesn't have to spend time mentally translating "fptsce" into "the function that finds the point source".
Keep it simple
Implement your algorithms in as straightforward a way as possible. Even if this risks your code being over-simple in the first instance and hence under-performing. It’s much easier to increase the complexity of your code if it really needs it (i.e. by adding features, using more efficient numerical algorithms etc) than it is to simplify already-complex code. A lot of the time, you’ll find that simple code is perfectly adequate, so you can just move on to the next chunk. Remember that you are not optimising at this point, you are writing the code. Write the simple version unless you absolutely, absolutely know it will be inadequate. If you end up needing a speed-up of a factor of a few, you can optimise later. Often you’ll find that for various reasons you don’t need to optimise this part of the code after all. Maybe it ends up not being the bottleneck. Perhaps your code ends up being plenty fast enough without any optimisations. Or maybe you end up buying a faster machine on which to run your code. Don’t waste time now!
The simplicity-first approach also has the advantage that simple code is easier to maintain and modify. A good rule-of-thumb is that a 25% increase in code complexity ends up costing 100% extra effort so, conversely, even small reductions in complexity can save a lot of effort.
The mindset of coding
Appropriate mindsets are often overlooked when something is being taught; the student is left to figure out one for themselves as they gain experience. And so it is with the craft of coding. But it shouldn't be! Adopting a good mindset can make you a much better code craftsperson. Remember, you’re building something that someone (possibly you) needs in order to do science. If you do a bad job then it will impact on the science that is done with it, so what you’re doing has value and you should be proud of it. Taking pride in a project not only makes it more enjoyable, it gets you through any stickier patches, when the coding is tough going, and it gives you the focus to find really good solutions when building the trickier parts of the code. Do a damned good job and be proud of it!
Attention to detail now will save you time later. Coding is not a race. It will generally be subject to a time constraint, but your job is to use that time as wisely as possible. This means paying close attention to the details of your code as you write them. Don’t leave problems for yourself at a later date; sort then out now when the code/algorithm/reasoning is refresh in your mind. Because of this freshness, time that you spend now will be much more valuable than time you spend fixing the problem in six months’ time, when you no longer remember the subtleties of what it was you were doing. Also take some time to consider what you are writing. And how it fits into the plan. It’s time well spent. It's easy to feel time pressure, especially when a deadline is looming, but working in a considered way will save you time in the long run (as you avoid problems before they start, make fewer mistakes etc). It just needs a bit of self-discipline (and faith) in the here-and-now.
Taking care, attention and a little pride in your coding will lead to much better crafted software. This will in turn lead to better results in the science you're doing. Combining this with a few basic, easy-to-learn rules and you'll already be well on your way to crafting better code.
No comments:
Post a Comment