Maintainable Code

Let’s face it, we all know that when we sit down and start coding anything, the requirements are going to change and once we have released the code into the wild our clients are going to want updates.

Let’s face it, we all know that when we sit down and start coding anything, the requirements are going to change and once we have released the code into the wild our clients are going to want updates.  So the real challenge with coding is writing something that can be easily maintained, whilst remembering that it may not be ourselves doing the maintenance.

Maintainability is probably the single most important thing in software development, so why is it that so often code becomes difficult to maintain, and the older the code gets the more difficult it becomes to maintain?  This post will give a very brief overview of some common techniques that should be remembered to help improve maintainability.

Meaningful and Consistent Naming Conventions

The first thing to remember is that someone else may be reading your code, and thus it is important that they can understand what a class, method or variable is doing based on the name given to it.  This is particular important with larger projects where developers need to be able to find functionality quickly, otherwise maintenance costs will increase.

There are quite a number of standard naming conventions around, so once you have picked one, stick to it.  If possible use tools that help you stick to those conventions.

Remove “Code Smells”

One of the major problems with code is that is can be full of “code smells” and over time the code can rot more and more.  Some of the common code smells are

  • Duplicate code
  • Large methods
  • Large classes
  • Excessive commenting
  • Conditional complexity
  • Dead code

For a fuller list with explanations read the Code Smells article on Coding Horror.

Separation of Concerns

SoC is about breaking the software into distinct pieces of functionality.  On a simple level this may mean separating the UI layer, the business logic layer and the database access layer.  If functionality is not separated out then it becomes difficult for developers to pin point the area they need to update during maintenance.  It is also likely that this mixed functionality will lead to making changes more complicated, due to code being reliant on other areas of code.

A major benefit of SoC is that it generally leads to much smaller methods and classes, thus improving the readability of code.  It also improves the ability to test each area of functionality.

Loose Coupling

Coupling is the measure by which each object relies on other objects.  If objects are loosely coupled a change to one object will have a minimal effect on all other objects.  One way of loosely coupling objects is to follow the Dependency Injection pattern.


Testing is an essential part of software maintenance.  If code is not covered by tests then it becomes difficult and time consuming for developers to check if updates have caused knock on effects in other areas of the software. Ideally a developer should be looking to practice Continuous Integration, and a build server should run the tests whenever new code is checked in.  This way the team members will know quickly if the build has broken and problems can be resolved quickly.

Final Thoughts

There are many more areas to creating maintainable code that haven’t been mentioned above, the purpose of this post is to act as a starting point.

Please lets us know how you ensure your code is easy to maintain.


3 Responses to “Maintainable Code”

  1. Sean Kelly
    June 6, 2009 at 2:05 pm #

    Nice article, and the basic principles all coders should follow from the starting block of their coding experience.

    When a developer encounters someone elses “spaghetti code”, their initial reaction is generally one of disbelief of the mangled mess in front of them. This however usually transcends into a source of amusement. I once enountered a naming convention of variables that began with I kid you not “aa”, “ab”…. which was even transposed into non-related database field names. Needless to say, the time trade off of debugging over a rewrite would have been excessive.

    The SoC methodology, or MVC (Model View Controller) paradigm is by far the best pattern of which most of the popular development library frameworks implement. Initially it can seem daunting & complex to follow, yet once the basics are grasped the development process can be vastly improved.

    A simple translation of MVC is;

    Model–>Structure–>(X)HTML–>Business Logic
    View–>Style–>CSS–>User Interface/Presentation
    Controller–>Events–>JavaScript–>Data Flow

    For more info

  2. John Polling
    June 6, 2009 at 9:34 pm #

    Those are some impressive variable names!

    My personal favourite is a project I have had to maintain where quite a number of pieces of functionality have been clearly copied and pasted between files, with maybe the odd minor tweak.

    It astounds me how often these basic principles are forgotten, especially when deadlines are looming on a project. Unfortunately this generally leads to higher maintenance costs.

    Is it possible that mentors are not teaching these principles any more? Has developing now become more about being able to use certain tools?

  3. Simon Parmenter
    August 31, 2009 at 10:23 am #

    You’ve forgotten high cohesion.

    Loose coupling + high cohesion = separation of concerns = single point of concept / responsibility / maintenance.

    For OO code the SOLID principles are a good place to start.

Leave a Reply

Leave your opinion here. Please be nice. Your Email address will be kept private.