Simple Ways to Write Maintainable Code

Writing maintainable code is something that comes naturally to some and only with a great deal of effort to others. It is within the ability of all programmers though – some just need a little encouragement to drop bad habits. I have been programming for many years now and I have seen a wide range of code which has differed in quality from the horrific train crash style code to the sun drenched gently rolling hillside style.

Over the rest of this part article I will try and describe what I, and many others, feel makes for good and maintainable code. None of the suggestions I will make here are difficult or time consuming to implement and will save many times the amount of time they cost. I am most comfortable when coding in Java so these guidelines have that language in mind. They are equably applicable to any language however.

Simplicity

Simplicity is, in my opinion, the key to maintainable code but simplicity means different things to different people. To me it means that within sixty seconds of looking at a piece of code you should have at least a vague idea what it does. Ideally you should be able to tell roughly what a method is going to do from its signature alone.

I believe simplicity also means avoiding use of obscure or difficult to understand language features unless they are necessary. No language is perfect; they all have aspects that the majority of developers rarely if ever use. Including one of these aspects is just asking for trouble when you or worse a colleague comes to maintain the code. In Java for example you can define static and non-static initialization blocks – how many developers that haven’t taken the Java certification exams even know this is possible? There is also the old ternary operator chestnut – the operator that code maintainers love to hate. I’m not advocating that your code should be the equivalent of a “Spot the Dog Goes to the Beach” children’s book, I believe it should be pitch at or just very slightly above the average developer.

If your code requires you to read volumes of documentation and then study each line in detail there is a good chance that it is too complicated. As with all these guidelines they are just that – guidelines. There are times when a method or piece of code just is complicated but you should aim to minimize these occurrences with good design. Use encapsulation to hide the complexity from the rest of the system and expose a clean and simple interface. Additionally, avoid the mistake of trying to hide complexity by producing hundreds of tiny methods. This is at least as confusing as trawling though one massive method that does all the work.

Aim to make your code as simple as possible and no simpler.

Comments

This will sound like a rather trite statement to make but comment sensibly. Too many comments are as bad, perhaps even worse, than too few. Too many comments and especially trivial comments will cause the maintainer to ignore them. All the effort put into writing the comments is then wasted. Instead comment blocks of code with one line that says what it does. If it needs more than three lines there’s a good chance it’s doing too much.

The one line comment in a method is useful because it means the maintainer can read that and have a pretty good idea whether they can simply skip that section when looking for a problem.

Method level and class level comments can be more verbose. Personally, I like to see thorough documentation of methods that actually do work. Simple getters and setters rarely get commented. Generally a method comment should not describe how the method does something only what it does. In practice if the comments are only intended for internal consumption it can often be useful to add a little information on how as well.