This document is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 License.
Up to this point, we have focused on making sure that the code we write works correctly; that it has no syntax errors and that it does what we want it to do.
Unfortunately, having code that successfully performs a task is not the end of our journey. It is also important that we make our code neat and tidy. Just like owning a car, if we want our code to keep working tomorrow and the next day and the day after that, it is important that we maintain our code and keep it clean. This section discusses the proper way to write code so that it will last.
There are two important audiences to consider when writing computer code. The obvious one is the computer; it is vitally important that the computer understands what we are trying to tell it to do. This is mostly a matter of getting the syntax of our code right.
The other audience for code consists of humans. While it is important that code works (that the computer understands it), it is also essential that the code is comprehensible to people. And this does not just apply to code that is shared with others, because the most important person who needs to understand a piece of code is the original author of the code! It is very easy to underestimate the probability of having to reuse a piece of code weeks, months, or even years after it was initially written, and in such cases it is common for the code to appear much less obvious on a second viewing, even to the original author.
It is also easy to underestimate the likelihood that other people will get to view a piece of code. For example, our scientific peers should want to see our code so that they know what we did to our data. All code should be treated as if it is for public consumption.
Paul Murrell
This document is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 License.