It’s a cliché in software development that every developer taking over a project will declare that the last guy’s code is terrible and needs to be rewritten. Surely the last guy thought his code was perfectly fine. Who is right? Both are.
Maintainability is a quality of code. An important one, in fact. The last guy understood his code and what it was doing so it was perfectly maintainable and so was of high quality. The new guy coming in can’t understand what’s going on and so to him it’s of low quality. The real question is: How can we make code more maintainable?
The most maintainable code is code that you yourself wrote in the last day or so. You can remember what you were doing and why.
The next most maintainable code is code that you wrote in the past. You may not remember what you were doing, but the code is familiar and so you can usually figure it out.
After that, the next most maintainable code is code that somebody else wrote and that person is still around. You may not understand what it does, but at least you can ask the author.
The least maintainable code is code that somebody else wrote and that person is long gone. You don’t understand what it does and there’s no way to find out other than to trace through it.
The way to make code more maintainable, then, is to get the least maintainable code – code written by another person long ago – to be as understandable as code that you yourself wrote 10 minutes ago. We can accomplish this with to things:
- Rigorous coding standards
- Extensive code commenting
Rigorous coding standards ensures that everyone’s code looks the same. This includes alignment, code ordering, and code naming strategies. For example, I ensure all my classes’ properties and methods are declared alphabetically. My team does the same. Any one of us can easily find any method or property in anybody else’s code.
Extensive code commenting means commenting nearly every line of code, even if it seems redundant. If you know what your code is doing, you should be able to write that down in good English. If you don’t know what your code is doing, you shouldn’t be coding. This makes reading code like reading a book – rather than trying to decipher a line, you can just read, in English, what it does. It adds a further validation step, which is that if what the code does and what the comment says the code does are different, this indicates a potential bug.
Getting developers to write extensive code comments is hard. Humans are lazy by nature and developers are as bad as any. Many mediocre developers got into the industry because they saw software development as a way to make a good income while remaining seated and not working too hard. A good developer, though, will understand the use of this technique and once he or she has experienced how much it helps the maintainability of software, will come to embrace it.
If you’ve achieved your goal, you should not be able to tell whose code is whose even in a large organization and any developer should be able to look at any other developer’s code as if it’s their own.
Dogs Chasing Squirrels 
Great article Mike. I have to agree on all fronts. I would add another category to why software is developed poorly: developers who were tasked with creating a proof of concept that was never intended to be production code. As you say, humans are lazy and the need to create something that was never meant to last provide no incentive to create maintainable code.
That’s a particular problem with students, since no assignment is ever meant to last, and so this is one of the standard speeches I give to new grads.
In fact, I gave this as a speech to one of the would-be new hires the other day and thought to turn it into a blog post.