Code For Maintainability So The Next Developer Doesn’t Hate You

Unless your problem domain includes some specific need for highly optimized code, consider what is your biggest coding priority. I’m going to suggest that you make it maintainability.

There was an online meme going around recently that suggested that you should code as if the person that will maintain your code is a homicidal maniac that knows your address. Okay, that’s over the top, but I would like to suggest you code like future changes to your code will cost someone money. Preferably, someone you like. The more time the next programmer has to spend figuring out why you did something, the more money it will cost.

Before I continue any further, I would like to apologize to anyone that has had to maintain any of the code I have written over the last, ahem, 20 plus years. Especially anyone who has stopped and said, “what was he thinking?” We all have “that” code out there, but I hope that I have less than most, as I am sure we all do.

How to Achieve It?

It’s easy enough to say you are coding for maintainability, but what should you do to achieve it? I’d love to see some suggestions in the comments. Here are some of mine.

No Such Thing as Prototyping

I had the pleasure to work with a team who had to maintain and extend a project that started its life as a prototype. A couple of bright programmers put together a concept they thought would benefit their company. It was quickly slapped together and shown to their bosses and a marketing type or two. I know a few of you know where I’m going with this. Within a month, the marketing types had a client signed on to use this new service. Having been thrown together without any real architecture, the product was a real problem to maintain.

I’m not saying never prototype, but when you do, keep in mind, this code may not be thrown away. Code the prototype using good software design skills.

Use TDD

I’m going to approach this from a different direction than most do. Yes, Test Driven Development is great for maintainability because if you break something, your tests will let you know it. But it also is a great way to document your code. Documentation in the comments is often wrong because the code changes, but the documentation doesn’t, or because the original programmer does not take the time to write well understood documentation. Or, most likely, the original programmer never gets around to writing the comments at all. As long as the tests are being run, they will usually be a reflection of how the programmer expected the process to perform.

If you fully test your code, the next programmer can get a really good idea of what you were thinking about by how you setup your tests. There is a lot you can learn by how you build the objects you pass into your code.

Don’t Be Cute

Sure, that way of using a while loop instead of a for loop is cool and different, but the next programmer has no idea why you did it. If you need to do something non-standard, document it in place and include why.

Peer Review

We all get in a hurry trying to meet a deadline and the brain locks up when trying to remember how to do something simple. We write some type of hack to get around it, thinking we’ll go back and fix it later when more sleep and more caffeine have done their magic. But by then, you’ve slept and forgotten all about the hack. Having to explain why you did it that way to another programmer keeps some really bizarre code from getting checked in.

Build Process and Dependency Control

At first glance, this may not seem to be an important part of writing maintainable code. Starting on any project, there is a huge curve in getting to know and understand that project. If you can get past spending time to figure out what dependencies the project requires and what settings you have to change on your IDE, you’ve cut down a bit on the time it takes to maintain the project.

Read, Read, and Read Some More

It’s a great time to be a programmer. There are tons of articles and blogs that contain sample code all over the Internet. The publishing industry is trying hard to keep up with the ever-changing landscape. Reading code that contains best practices is an obvious way to improve your own code and help you create maintainable code. But also, reading code that does not follow best practices is a great way to see how not to do it. The trick is to know the difference between the two.

Refactor

When you have the logic worked out and your code now works, take some time to look through your code and see where you can tighten it up. This is a good time to see if you’ve repeated code that can be moved into its own method. Use this time to read the code like a maintenance programmer. Would you understand this code if you saw it for the first time?

Leave the Code in Better Condition Than When You Found It

Many of us are loath to change working code just because it’s “ugly,” and I’m not given out a license to wholesale refactor any process you open in an editor. If you’re updating code that is surrounded by hard-to-maintain code, don’t take that as permission to write more bad code.

Final Thoughts

Thinking that your code will never be touched again is many things, but especially unrealistic. At the very least, business requirements change and may require modifications to your code. You may even be the person that has to maintain it, and trust me, after 6 months or so of writing other code, you will not be in the same frame of mind. Spend some time writing code that won’t be cursed by the next programmer.

- Rik Scarborough, asktheteam@keyholesoftware.com