The Rules for Writing Maintainable Code

[magazine]
Volume-Issue: 
Summary:

We've all been burned working with software code that, if not designed for long-term maintainability, results in expensive support over a product's lifetime. Kaushal explores three approaches that provide guidelines to ensure that software is designed with maintainability in mind. If you're a software developer, read this!

When a developer writes code, he imagines that he will be the only one working on it in the future. But the reality is that someone else will have to work on it. This may be due to a number of reasons: New functionality may be required, changes will be needed for existing features, and fixes for defects will need attention. The latter is a certainty. All of this work is often performed long after the original code was written and by a  developer who did not write it. The challenge is to make changes without breaking the existing code. This situation can be complicated by the fact that there may be little technical documentation summarizing what the code actually does, and any future work will typically have tight schedule demands.

If we accept Robert L. Glass’s assertion in his post “Frequently Forgotten Fundamental Facts about Software Engineering” for the IEEE Computer Society [1] that software maintenance accounts for 40 to 80 percent of total software development costs, then we can understand the importance of writing maintainable code from the start. Focusing on rushing the product out the door and failing to make code easily understandable for those who will work with it in the future dramatically increases the cost down the line.

Starting over from scratch because you’re afraid that everything will break if you make too many changes is hugely disruptive and costly. It’s a simple truth that the more maintainable your code is from the start, the longer its lifecycle will be.

The question is, how do you write maintainable code? These three simple rules will keep you firmly on the right track.

1. Write Code that Is Easy to Understand and Debug

If the next developer to work on your code can’t understand what you’ve done or why you’ve done it a specific way, then they’ll usually throw that code away and start over. It takes longer to understand poorly written code than to write new code from scratch. Write structured code with a clear format, follow conventions, and, if it isn’t self-explanatory, make sure the code is fully commented. Here are a few best practices.

Choose a clear coding style: Keep your function and data naming consistent.

Optimize for the reader, not the writer: Saving time while you write code can cause serious frustration and confusion for anyone reading that code later.

Include concise comments: If it isn’t obvious what’s happening when you look at the code or you’ve implemented something a little unusual, make sure you include good comments to explain it. Don’t write your  comments for yourself—imagine someone else trying to understand your code cold.

Always do the smallest, simplest thing to add value: Always focus on the task at hand and write the best code you can to achieve your current aim. Don’t do anything unusual. Writing code with one eye on future  requirements is a recipe for disaster. Designing your code in a modular fashion with separate, discrete parts is much easier to understand.

KISS (Keep It Simple, Stupid): Don’t assume the next person working on your code is going to be at the same level of understanding or experience. Write code that a novice can understand and leave out the  experimentation and excessive optimization out.

Tags: 

About the author

Kaushal Amin's picture Kaushal Amin

Kaushal Amin is Chief Technology Officer for KMS Technology, a provider of IT services across the software development lifecycle with offices in Atlanta, GA and Ho Chi Minh City, Vietnam. You may reach him at kaushalamin@kms-technology.com.

Upcoming Events

Oct 12
Oct 15
Nov 09
Nov 09