One of the most important determinants of a project’s success is how maintainable the software is. Maintainability in turn, is often driven by soft factors – factors that can’t be quantified or easily measured. This is one reason why so many projects churn out software of poor quality and consistently miss deadlines. A company can have great engineers, the latest tools and technologies, and enforce strict software processes but still create unmaintainable software. Instead of solely relying on things that can be written in a list and checkmarked, one must work on developing a culture of simplicity. Once such a culture exists, the creation of quality, maintainable software will be the natural outcome.
The Twin Plagues of Under-Engineering and Over-Engineering
Before I get into what to do right, I want to touch on a couple problems that commonly derail a project. Too often software design and development end up falling prey to one of two extremes: over-engineering or under-engineering/hacking.
Under-engineering is easily explainable and we’ve seen it all before. Individuals who do not coordinate with each other or simply just learned bad habits often don’t put into practice a good design strategy. Eventually the code starts to resemble a giant ball of twine and bug fixes that should take hours end up taking days or even weeks.
Just as common, but perhaps less recognized is the over-engineering phenomenon. Often this is the result of individuals who have learned various design patterns and believe that they should be (over)used at every turn. Also known as being ‘pattern-happy’, this tendency can actually be as dangerous to the success of a project as under-architecting a system. Over-engineering behavior is problematic because it causes finite amounts of overhead code to be included for every bit of functionality implemented. Over time, these bits of overhead start really adding up and negatively contribute to the maintenance cost of the product.
The end result of over- and under-engineered systems is the same - maintenance effort of the software becomes onerous for even the simplest of functional additions. This maintenance overhead results in regularly missed schedules and frustrated developers.
The Four Pillars
Remembering what I call the four pillars of maintainable software will help ensure that your product doesn’t become an unmanageable beast.
Note that these may seem somewhat obvious at first glance, but they’re easy to ignore or brush off. You’d be surprised at the number of individuals who claim that their development techniques adhere to these principles but whose work shows a complete disregard for them. You'll notice that I don't cover some concrete recommendations we've all heard before such as commenting code. At this point the vast majority of developers know that they should be commenting code, however many overlook more nebulous aspects of successful software development that, in my view, are even more important.
Pillar 1: KISS – Keep it Simple Stupid
Many have heard of the KISS rule – Keep It Simple Stupid. As it implies, this indicates that you should always maintain simplicity in every aspect of your product – from the design, to implementation, even the software process. The inherent complexities present in large projects make development and maintenance hard enough without unnecessary overhead being introduced into the product by various individuals.
KISS is a mindset that should be drilled into everyone working on the project. Many or even most people do not have a true appreciation for complexity and often greatly underestimate the negative impact that small amounts of complexity can have on a product over time.
A few example questions showing where KISS could be applied:
- Why are we implementing this design pattern? Is there a simpler pattern that would be more efficient and easier to maintain?
- Is there a simpler way to implement this bit of code?
- Does every part of our process make sense or are there ways to make it more efficient?
- Are there parts of the code or process that we tend to repeat over and over that could be simplified?
Pillar 2: YAGNI – You Aren’t Going to Need It
From the world of Extreme Programming comes the YAGNI, or the “You Aren’t Going to Need It” rule. As the name implies when designing and coding really think if the bit of functionality you are adding is definitely going to be needed or are you just putting it in ‘just in case’. More times than not these ‘just in case’ additions end up never being used and simply add to the maintenance overhead of the product.
If you keep the code as simple as possible and if you end up needing a bit of functionality later, it is usually no big deal to insert new functionality because the code is very simple and you have good test coverage, giving you confidence that you won’t break anything at a later date.
The XP/Test Driven Design community takes a harder line than I tend to – they claim that even if you KNOW functionality will be needed in the near future but not at this immediate moment don’t put it in. I tend to go with the idea that if I know for a fact that functionality will be needed and I’m already in that bit of code or designing that part of the system go ahead and put it in.
YAGNI example questions:
- Is this bit of functionality I’m implementing absolutely needed right now?
- Is this bit of functionality that I’m implementing highly likely to be needed in the future or am I doing a ‘just in case’ that has a decent chance of never being utilized?
Pillar 3: DRY - Don’t Repeat Yourself
DRY is a rule that actually drives a lot of design patterns and refactoring recommendations. One of the biggest maintenance problems is when you have code repeated throughout the project. What tends to occur in these cases is when one of these code copies needs updating, developers need to search throughout the code base and update all the copies. Sooner or later one or more copies ends up not getting updated and you get bugs introduced. Additionally, copies of logic adds to the sheer volume of code needing to be maintained which makes for a more confusing product in general.
So in short, when you see a piece of code that you are copying/pasting, extract it into its own method or module. It will be much less bug-prone and easier to maintain in the future.
Pillar 4: Stay Organized
Stay organized in every part of the project; from where you place documentation on the company server, to how you lay out your code files, to how you name your classes, to how your product is being installed, even to making sure you refer to various concepts in a consistent manner when speaking and writing about them.
I find that proper organization is often under-stressed in software projects, which is a shame because poor organization can decrease maintainability as well as the chances of long term project success. When things aren’t organized that means that the team members need to employ raw memorization of random bits of information.This memorization overhead takes away from having a clear head to solve problems and muddles communications between team members. Therefore, poor organization can lead to the introduction of ‘dumb’ bugs and can even indirectly cause project schedules to slip.
Ensuring that all parts of the project are organized cuts down on ramp-up time of newly hired individuals as well. This is because when a project is properly organized, the company isn’t as reliant on the tribal knowledge of existing members. New members will be able to more easily figure out how things work and where information is, simply by following consistent patterns.
It’s all about a Mindset
The pillars may seem obvious and even a bit mundane, however they are intended to reinforce a mindset of simplicity which leads directly to the creation of maintainable, quality software. In addition to hiring talented individuals, shops have to ensure that the culture reinforces good software development. The culture can’t be just about pushing deadlines, giving lip service to code quality and stating that if we only implement patterns x, y and z that all will be OK. The mindset encouraged by the project is critical to the production of maintainable software.
Aside from the four pillars, there are quite a few software design heuristics that I have found to be important in making sure that code stays clean and easily maintainable. I’ll be writing about these in the near future.
Robert Riley has been developing software professionally for over 10 years in several industries (both direct and as a contractor). If you are interested in contacting Robert, simply send him an email at This e-mail address is being protected from spambots. You need JavaScript enabled to view it .
