Put simply programming is writing instructions for the computer on what to do. That part is easy.
The other side of it is writing the instructions so future maintainers can work with the code without making too many mistakes. That’s much harder.
The future maintainer (often a slightly older version of yourself) needs to:
- Understand what the code does.
- Change the code.
- Expand the code.
Mistakes (or bad planning or bad luck) that leads to problems changing the application often take a long time to really show up. You can always squeeze something in to change “just one more thing”.
Problems that makes it hard to expand the code can be hidden the same way; most expansions are really just a bunch of small changes and until some fundamental change (“now also do it in Chinese”, “do 10 times more requests”, “support multiple currencies”, “now with 2 terabyte data, please”) the technical debt won’t completely stop you.
Mistakes that makes the code hard to understand on the other hand can show up very quickly. All you need is a break from the code and then coming back to it a few weeks or months later (or days if your memory is more like mine).
One of the easiest mistakes to make is poor naming of a variable. The obvious mistake is to call some important variable x, obj or data. Which data is that now?
In the YellowBot code most of our data revolves around “locations”, so we have a lot of location this and location that. A common mistake then is to do something like
for my $loc ($foo->location_widgets) {
...
}
The mistake here is that $loc isn’t a location, but a location_widget. If it’s 3 lines it’s not so bad, but soon enough the loop is 10, 15 or 30 lines long. When you go to make a change it’s easy to think $loc is a location object and not a widget. Boom; game over!
Another similar mistake is to have multiple data structures for (too) similar kinds of data.
A month ago I redid our “process videos” infrastructure (mostly used by Weblocal where they have a lot of videos). Today I noticed that we don’t process videos with more than 2 audio tracks properly to all the different output formats. Simple change! The “what codecs are in the file” code already extracts the number of audio tracks, so I can just add a few lines to force the number of output channels to 2 when needed.
Around where I need to add this code there are some lines with $meta->{bitrate}. Since I could see from our debug output that the key for the audio channel data is called audio_channels, I can just add $meta->{audio_channels}, right?
Wrong, of course.
In my infinite wisdom I had separated out the data from the “detect video meta data” and “other data we’re calculating in this code”, so the former is stored in $video_info and the latter in $meta. At the time I’m sure it seemed cleaner to keep the two data structures separate; but now a month later it makes no sense - how can I, easily, know if the data I need is $video_info data or $meta data?
Take a month away from a bit of code and then come back and see if it still makes sense. It probably won’t.
