Maintainable Code
What is it and Why is it Important?
It’s basically a philosophy on how to develop efficient code that can be understood and worked on by other folks. Cause let’s face it, unless you’re the sole developer of the product, your code WILL be touched by somebody else. And if your code can’t be easily understood by other developers, it’ll have consequences like increased cost, higher chances of defect, and delayed releases – all of which may ultimately cause your company to miss the market.
William Wong March 2017
Software Lifecycle
The lifespan of a software can be broken down into three phases.
-
R&D: this is the stage where they come up with the idea and develop a proof of concept.
-
Maintenance: this is where features are tweaked, enhanced and modified based on customers’ feedback. This is also where developers work out the kinks in the code.
-
Sunset: where a company ends support of the product.
Out of the three, the Maintenance phase takes up the longest period, often as long as 10 years or more. Things can get pretty ugly during this phase because the software is being maintained long after the original code was created, and by people that weren’t the original developers. The situation gets even harrier if there are little to no documentation on what the code actually does. Software Maintenance accounts for 40-80% of development costs and continues to rise. This is why the Maintainability of code is so important.
Example
Let’s put things into perspective. Imagine two competing software products that provide the same functionality. We’ll call them Company A and Company B. If given the same input, both products will deliver the same output. But let’s look at the differences.
-
Product A has source code that is impossible to understand. It takes a long time and tons of effort to make changes to the code. When customers suggest better ways to use the product, it takes the team forever to adapt. As a result, their software is extremely difficult to use. New releases are few and far inbetween. Due to the complexity of the code, when changes are made, you can never be too sure it’s bug free. Customers complain that their product crashes quite often.
-
Product B has source code that is easily understandable, so when users ask for change, they can deliver fairly quickly. They’re also able to push out new features quite often and their product is very stable.
Which product do you think is going to win and maintain marketshare? It’s a no brainer who the winner is (HINT, it's Product B).
3 Simple Steps to Maintainability
So now we know the importance of Maintainable code, how do you actually write code to follow this standard? We recommend 3 simple steps.
The first one tackles time efficiency. If you break down how a developer spends their day, you’ll notice they consume 5x more effort to modify code than writing new ones. It also takes 3x as long to understand code than modifying them. To help with this time sink, we bring you rule number 1.
Rule 1: Write code that is easy to Understand and Debug.
-
We achieve this by utilizing the KISS method and write code that even a caveman can understand. Keep the code as simple as possible to get the job done - no more, no less, and definitely nothing clever.
-
Don’t try to solve all problems at once. Break it down into the smallest, simplest thing that adds value. It should have separate and discrete parts. For example, functions and classes perform only what they are intended for. This is important because if there is ever a change request, your code will be easy to dissect in order to locate that particular component that needs change.
-
When it comes to documentation, our philosophy is that it should be supplemental. Your code should be self-explanatory. If you need a lot of documentation to explain something, then it’s too complex. Code should be short and clear on its own. Name your Functions and Variables correctly so they act as documentation. This does not mean there should be ZERO documentation, but just enough to act as support.
Rule 2: Write code that is easy to Modify and Enhance.
This rule deals with change, specifically, how easy is it to add new features or modify existing ones. For example, if a single change breaks your code in 10 different places, then you’ve got a real problem.
-
You do this by utilizing the DRY method, or Don’t Repeat Yourself. If you’ve copied your code and pasted it for another solution, then you’re introducing multiple points of failure should that initial code fail.
-
You should also practice separation of concern, which basically means if the code needs to do 10 things, then separate them into 10 different modules that each does that specific thing. This way if something breaks in one of the modules, it doesn’t take the 9 other modules with it.
-
The last item in Rule #2 is to just avoid long statements and crazy nesting. Doing so just makes it really hard to understand if it’s that complex, should probably be broken down into smaller pieces.
Rule 3: Write code with Test in Mind.
This brings us to our last rule, which deals with assurance. The assurance you get knowing the code you dished out actually behaves like it’s supposed to and the piece of mind that should you ever change anything, it’s still works afterwards.
-
Testing is so important that there should be an automated unit test implemented for every change made. There is even a certain school of thought that has you create your test first, like in the case of Test Driven Development. Whether you test first or last, develop your code so it can easily be Unit Tested.
So there you have it, the 3 step approach to writing maintainable code.