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

Rik Scarborough Programming 7 Comments

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.

See Also:  Go To SQL

If you fully test your code, the next programmer can get a really good idea of what your 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.

See Also:  More on Accessibility-First Programming

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, [email protected]

Comments 7

  1. First and most important, know your programming paradigm. Are you doing OOP (then are you using encapsulation, information hiding, “Tell, don’t ask”)? Are you doing functional (do you know the functional design-patterns out there?). Learn the paradigm you plan to use should be high priority.

    Sure, code reviews and refactoring are good tools, TDD also, but learn the programming principles (or, at least, invest some time in understanding some of them). Then learn (more clean coding) practices.

    It is quite sad how people use all the tools they can find, but never look for tools for the minds (what can leverage most your programming, beside knowing what your language was built for).

    On another note, “Don’t be cute” should be escalated to “Don’t be stupid” (or, on a positive note, “Be smart”). Name things for what they are, not where you plan to use them, thus make sure people understand what you built; don’t over-engineer, this reduces complexity… programming is complex as it is; think in business concepts (not programming concepts) and stop putting all Controllers into a .controller package.

    Love that you mentioned “peer review”, “refactor” and the golden rule “leave the code in better condition than when you found it”.

  2. Great, but I still think comments left around codes are great way to code for maintainability. Most times, if you have to create a document, you would be unable to update each section as you update your code, else you might be writing a book.

    1. Ekene, I love to jump on the documentation band wagon. In this case I agree that good documentation is valuable. The problem is that to be good documention it must be accurate, up-to-date, and relevent. The most common form of bad code documentation is doc that tells me what the code does. I can read the code, so I do not need that explained. Tell me WHY or tell me context. One distinct example of bad documentation was the C++ class libraries that had documentation on the setForeground(Color foregroundColor) method that stated “set the foregroung color”. Normal getter/setter methods don’t need doc about what they do, but telling be on a getter how the foreground color is used is helpful.

      Maybe my expectations are too high, but as soon as I see hard-coded text in a class that is out-of-date, I no longer trust any of the documentation. I agree with Rik that the best form of code documentation is a runnable test suite. Testing by specification that takes on the form of Given…/When…/Then… clearly gives me context, tells me what to expect, and is runnable which ensures accuracy.

      Rik, instead of cute, though, I admonish fellow developers for being clever. In college, back in the dark ages, I wrote a single line of code that performed a complex calculation that accounted for several distinctly different logic paths. I was very proud of my cleverness in compacting a large amount of code into one line. There is no way anyone would ever be able to maintain it or even understand how it worked. Great for a class assignment; awful for business applications.

      Maintainability, to me, is as important as performance, usability, and reliabity. Great blog.

  3. Ekene, I agree that comments around the code are important and a good way to ensure maintainability, if the comments are correct to begin with and maintained along with the code around them. Unfortunately I’ve seen too many examples of both not happening. Still, I try for the best.

    I’ve worked at several companies that require separate documentation, basically the book on the code. It’s typically created when the code is ready to go into production, placed on a shelf where a quality assurance person would find it and check it off the list, and then it is never touched again.

    Keith, excellent example of what I meant by being cute, or clever if you rather. This is exactly what I was talking about. Great for the ego, until you’re the one that has to go figure out why it was done, and sometimes, what it is trying to do.

  4. I would suggest “Clean Code “by Robert C. Martin as a primary resource for getting into thinking clean code, though that clean code pretty much touch upon everything that is associated with best practices within software development, from On-click deployment, over testing, to naming your identifiers.

    1. Thanks, Michael. I added Clean Code to my to-read list. Looks like a very good resource. Thank you again for the suggestion.

What Do You Think?