The Code of Christmas Past

When we write code, we’re often thinking about the short term. We need this code to function correctly so we can deliver within our immediate deadlines. I’ve found it important to also think of the long term. Sooner or later, we might encounter our own code, again.

I spent a chunk of my career where I often worked solo on projects that might get enhanced every year or two. This taught me a lot about the importance of code readability and what sort of things helped me quickly understand and avoid overlooking important considerations. I’ve also worked on a lot of legacy code bases, so I’m well aware of the pain and problems created by code that’s not readable, or is not organized in a helpful manner.

Last week at the AgileDC Conference, someone told me they were working on code I had written ten years ago. My first question was, “Are the unit tests still working?” This code was the first production code I ever wrote test-first, and it taught me a lot doing so. I was glad to hear that they had been maintained. When I was writing them, I couldn’t get anyone else interested in test-first development.

Even more gratifying was hearing that they’d recently used some of my code as an example in a discussion of object-oriented programming. The example they’d used was where I’d wrapped an integer in a class. Why would I do that? Because it wasn’t really an integer. It was a database ID. The integer was just an artifact of the database automatically creating ID values using a sequence. It would make no sense to perform arithmetic on it. And there were IDs for various entities that should not be used interchangeably.

Class diagram for a class wrapping an integer

The integer value was intended to be used only within the Data Access Object that read and wrote the database.

A few years ago, I was asked if I could change an algorithm in some embedded assembly code that I’d written more than ten years prior, and I hadn’t even seen for over ten years. Setting up the development environment wasn’t easy, as much of the hardware was no longer manufactured. The code, however, was not hard to modify. I had implemented the algorithm using state machines and data tables, and had created semi-readable constants for all of the “magic numbers” used.

Code is read much more frequently than it is written. Writing it clearly and expressively pays off when we have to read it next week or next month. Well-written code is also much more likely to be useful for decades into the future. If you write code only for the short term, it’s likely to have only a short life. People will find it necessary to rewrite it rather than maintain it for the long term.

3 Comments

Categories: Tools and Techniques

Tags: , ,

3 Replies to “The Code of Christmas Past”

  1. Back in the day (1965-ish) in my first software house, I used to give twelve-month guarantees that the code would work as required, as long as it was maintained by us. Our programmers were good at writing clean, self-documenting code, and we delivered into IT departments, so the guarantee was almost never invoked because if they found a problem, they’d have a glance at the code and decide to fix it themselves. So both sides won.

  2. Hi George,

    I learned a very valuable lesson very early in my career.

    During the summer after my first year of university, I had built a small inventory tracking application for a group where I worked. After second year, I returned to the same group, and they asked if I could make some modifications and add some new functionality.

    I said, “Sure!”, and opened up the code. My first reaction was, “Who wrote this s#&t?!”. My second reaction was a vow to, from that day forward, always write readable, understandable code that was a simple as I could possibly make it.

    Fast forward to about 10 years ago, and I was sitting with a Business Analyst who wanted a slight change to a feature. I opened the source and started to have a look when she said, “Wow – I can actually understand what that code is doing!”

    That was by far the best compliment my code has ever received. I don’t care if another programmer thinks the code is ‘elegant’, and care even less if another programmer thinks it’s ‘clever’. If the code passes all the tests, does what the business wants and a non-programmer can understand what the code is doing, then I’m pretty damned happy! 🙂

  3. From a purely business perspective, we are hired to create a product of value to our employer. If one writes code that is unreadable, the value of that code is only for that single application that it is running.
    However, if you write code that someone can understand, its more likely to be reused rather than re-written. For a little extra effort, you have increased the value of your product.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.