Three Attitudes that Lead to Maintainable Code

When writing code, there are many specific principles that aim to make your code more maintainable: DRY, the single responsibility principle, the Law of Demeter, the open/closed principle, etc. These are great principles to follow, but it can be difficult to keep all of them in your head at once. I’ve found it’s often easier to keep a few broader ideas in mind.

Change Your Perspective

As I’m writing code, I try to constantly review it from the perspective of a new developer joining the project. I imagine what it would be like to read this code for the first time.

Would I understand the overall flow? Have I used terms in a way that is consistent with the rest of the project? If I had to search for this thing without knowing what it is called, would I be able to find it quickly?

At Atomic Object, we often do pair programming, which is a great way to immediately get answers to these questions from someone who is not you.

One of the best ways to ensure that your code is maintainable by someone else (or your future self) is to make it self-documenting. I don’t mean that you should add comments all over the place. Comments should be reserved for the rare bits of code that are influenced by factors beyond the code itself (for example, a customer requirement or a bit of historical context). But rather, put serious thought into the naming of everything. After all,

There are only two hard things in computer science: cache invalidation and naming things.
— Phil Karlton

Neatness Matters

Have you ever seen an obfuscated code contest? Yes, it is possible to write code that does something useful and yet is completely unreadable itself. Those contests are just for fun, of course, but it can be easy to slip into bad formatting habits (or apathy toward it altogether). Code that is pleasing to look at also tends to be easier to scan quickly.

Compilers are actually pretty good at parsing and optimizing code, while humans are not. Take pity on the puny humans, and write code for them first, with the machine as only a secondary concern.

Prefer clarity over cleverness. Readability counts for far more than small optimizations. Brian Kernighan said it best:

Everyone knows that debugging is twice as hard as writing a program in the first place. So if you’re as clever as you can be when you write it, how will you ever debug it?

Avoid Special Cases

Few things will wreck your code faster than special cases. These are the things that take your nicely constructed machine and poke holes in a few of its tubes. It might seem easier in the short term to just slap some duct tape on it and try to ignore it, but if you don’t fix the root issue, it’s just going to spring a leak again later on down the road.

This might look like a quick-and-dirty fix to get something working in time for a release. It might look like reusing a component for something it definitely wasn’t designed to do. It’s those things that mostly work but have a few nasty jagged edges.

It can be tempting to simply use something that gets you most of the way there, but it takes discipline to refactor that thing so it gets you all of the way there. It’s worth it!

Conversation
  • michael rice says:

    Great article, thanks for taking the time to write it up. I’m curious what your experience is when discussing these points with our developers or clients — how do you go about it?

    • Brian Vanderwal Brian Vanderwal says:

      Internally, we often have open discussions on all sorts of development-related topics. I think this comes naturally from our company values (https://atomicobject.com/culture), one of which is “Teach and Learn”. In my experience, nobody knows everything and everybody knows something (that is, everyone has something to teach, and everyone has something to learn).

      Another one of our values is “Act Transparently,” which drives our interactions with clients. In my (relatively short) experience, these questions of code maintainability don’t come up too often. But when they do, we explain why it’s necessary and make sure the client is in agreement before moving on.

  • Matt says:

    Write tests and write code that is easy to write tests for. Tests are built in examples on how the code is intended to work which can often be more helpful than apt naming schemes or comments and documentation. Writing functions that can easily be tested also leads to more modular, less complicated architecture because it forces developers to break processing down into reasonably sized and scoped pieces.
    This practice is enforcible and practical where the idea of “pretend you’ve never seen this code before and decide if it is easy to understand” is not.

  • tony kwong says:

    Neatness, really? Code beautifiers have been around since the 60’s, and all modern IDE make this pretty much a one click operation.

  • Prasad mhatre says:

    4 th point is take your time to code. As Rome was not build in a day, similarly you can’t write a good maintainable code with deadline. When you have deadline then it’s obvious that there is high possibility of shitty code.

    So ask your boss, client to give you ample of time to write a code. Because if you are writing a code with deadline you are making a fraud, your are cheating yourself. You are going to have imposter syndrome.

  • This is exactly what I’m trying to teach my team. However, our project manager and architect are telling me that I go too far with this. They say it takes more time than needed, and that we need to focus on delivered functionality. How would you deal with this situation?

    • Tom Rutgers says:

      The whole point of having a project manager or architect is to evaluate what can be done in a certain time for a certain budget. It is not however, telling individual team members how they should work or what is needed to deliver a product. Try to explain them why your way of working is a requirement of getting the job done well.

      On the other hand, maintainable code is a pretty basic requirement. If you write your code in a way your fellow dev’s can understand what it does, and do so in a consistent matter, chances are you’re doing just fine. It’s not an art form or anything..

  • Dave Stagner says:

    There’s a slight bug in the first section. The two hard thing in computer science are cache invalidation, naming things, and off by one errors.

  • Comments are closed.