Maintainability is a major stake of professional software development. Indeed, maintenance is nearly always the longest part of a software life cycle, as it lasts from the project release until basically the end of times.

Moreover, projects being in maintenance represent a large majority of the overall number of projects. According to http://www.vlegaci.com/298/interesting-statistics-%E2%80%93-numbers-of-programmers-in-maintenance-vs-development/, the proportion of projects being in maintenance is about 2/3.

I recently came across this question, where the guy looks pretty surprised discovering that his job is mainly about maintenance. I then decided to open a discussion (french) on the main site of the French community of software development professionals (http://www.developpez.com/). The discussion is entitled "Are students well-enough trained to the reality of professional software development?" and is mainly about maintainability. It was pointed out that, at least in France, people are not well-enough prepared to face maintenance in both aspects of it:

  • maintain existing code
  • make maintainable code

My question here echoes to this discussion and aims at finding a good way to teach maintainability.

  • How can we teach maintainability?
  • What kind of exercise would you suggest?
  • If you have been well-trained regarding maintainability, what particular kind of courses did you take?

[edit] After some misunderstanding, I think I must clarify my question. As a project leader and software developer, I often work with trainees or freshly graduated students. I once was freshly graduated myself. The thing is that students are usually unfamiliar with principles such as SOLID that increase the maintainability of a project. We often end up having important difficulties making projects evolve (low maintainability). What I am looking for here is a concrete academical example of successful teaching about the importance of maintainability and how to make better code regarding this particular point; or possible suggestions to improve the way students are trained.

  • 1
    Possible duplicate: programmers.stackexchange.com/q/137672/18748
    – PhD
    Commented Apr 28, 2012 at 4:41
  • PS: Look at my answer there, you may find the spaghetti experiment worthwhile
    – PhD
    Commented Apr 28, 2012 at 4:41
  • @Nupul As you are a teacher and look involved in teaching code maintainability, please make a complete answer and tell us how you proceed : spaghetti code is only a small part of it Commented Apr 28, 2012 at 10:19
  • Posted an answer...hope it adds value for you :)
    – PhD
    Commented Apr 28, 2012 at 18:58
  • The API design and maintainability project in "Practical API design" is, IMHO, a project perfect to teach students the challenges of maintainability (and backwards compatibility).
    – Marco
    Commented May 2, 2012 at 11:59

7 Answers 7


How can we teach maintainability?

That's a matter of practice.

The most straightforward way of practicing it in a controlled way I can think of is to simulate typical maintenance project about as follows.

Get some project (Project A) that is well done and introduce few issues over it: inject some bugs, a good doze of duplicated and dead code, drop some features, unit tests and documentation here and there etc. You may even have a dedicated name for that, like Project A - damaged version.

Establish an issue tracker and fill it with requests corresponding to particular damages you made. Establish basic rules and practices for development process - VCS commits, code reviews, QA etc - consider taking what you can from check list provided in The Joel Test.

  • coursework 1.
    Fix bugs, add missing unit tests, documentation and features.
  • coursework 2.
  • coursework 3.
    Maintenance / improvement of original projects to use by next year students
    - Project A version 2.0 and Project A - damaged version 2.0, respectively.
    By improving damaged version I mean making better educative damage to it. :)

Of the practices mentioned above, pay special attention to that of code reviews. This is likely the most effective way to ensure that code is easy to maintain, as indicated eg by the top answer in related question.

WTF's per minute


Disclaimer: I just got my CS degree. I'm not a teacher.

This may sound obvious, but I think the best way to teach code maintenance is to have students perform code maintenance. Here's what I would do:

  1. Take a moderately complex problem, and two implementations that are semantically identical, but one is much more maintainable than the other.
  2. Request a number of changes/feature additions that are much easier to implement on the better code base. One half of the students have to implement these on the more maintainable code base, the other half on the less maintainable one.
  3. For the sake of fairness, you may want to repeat this exercise with the roles reversed.
  4. Compare the average number of successfully implemented changes between the good and bad code bases, and the time spent on implementing them. Have students share their experiences, air their grievances, and just generally talk about the work they've done.

The idea is to not only have students work with someone else's code, but to also have them develop an appreciation for maintainable code that will hopefully improve their design skills.

  • +1 for the exercise. That's very similar to something I've wanted to run for a long time; though in my version, students would write something to a spec, then it would be given to somebody else (chosen by me) to modify. You could repeat the activity after teaching about maintainability and good practices, to make your point.
    – Andy Hunt
    Commented Apr 28, 2012 at 11:31
  • 1
    You could put together a really good mini-course on maintainability based on the "code smells" chapter of Fowler's Refactoring.
    – mjfgates
    Commented Apr 28, 2012 at 12:05

Maintainability is a virtue, not a skill. There are many paths to creating maintainable projects, but no one formula that's guaranteed to produce them.

If you value virtues like kindness and generosity, you look for ways to practice the same in your daily life. It's the same with maintainability: if you and your organization value maintainability, you'll keep it in the back of your mind while designing and implementing your project. It will be a legitimate reason to spend a little extra time building something because you know that maintainability is appreciated. Conversely, spending extra time for the sake of maintainability in an organization that doesn't value it is discouraged.

If you want to teach people to make things maintainable, you should start by making it clear that your organization values maintainability. Specify it in the requirements for your projects. Make it one of the criteria for successful code reviews. In short, make maintainability part of your culture.

Next, be willing to devote some resources to improving maintainability in your existing projects. Identify those parts of a project where bugs keep cropping up, or where fixing bugs or making changes is very difficult and takes a long time, and redesign or refactor to facilitate maintenance.

Finally, indoctrinate new developers into your culture of maintainability by assigning them to teams that already practice it daily. There's no better way to help someone adopt a value than to give them plenty of good examples and guidance.

  • 1
    I'm having a hard time understanding the downvote here. You can recite software design from your bible of choice as much as you want, but the major problem is that developers are often under the impression that it doesn't matter because nobody cares to provide them with a better alternative from what they've done. If you do not instill the students with the sense of importance to constantly doubt the quality of of work they're producing and question the decisions they're making, then I really doubt how much a course on maintainability could prove useful to them. Commented Apr 28, 2012 at 19:18
  • @FilipDupanović Agree. Going a step further, although people bemoan the lack of preparedness of new grads with CS degrees, I don't think the issue is either surprising or unique to programming. Of course there's a difference between a new grad and an experienced worker: one has experience! A good degree program in any field is conceptual, not vocational. Only experience will teach new grads to apply the concepts they've learn and work effectively at whatever job they end up in.
    – Caleb
    Commented Apr 28, 2012 at 19:46

I for one dislike the term Maintainable in relation to software development. The reality is that all software is maintainable in that it can be subject to maintenance work, so the real issue is whether software is expensive or inexpensive to maintain, relatively speaking. I know this sounds like a very pedantic statement to make at the beginning of an answer, however my point will become clearer in a moment.

The problem with IT degrees which major in software development is that they really only teach students the barest minimum that the students need to know about writing software. Professional skills and knowledge is earned through the learning that is done in the first few years after qualifying for the degree. This is when a graduate starts to work on projects that actually matter to a customer, in an environment where there is great pressure to perform, and the expectation is to create a product to a professional standard. Sadly, many companies don't encourage a culture where professional standards in software are maintained, and they end up with projects that turn out to be costly to develop and maintain as a result. Unfortunately for our graduates, they learn a lot of bad habits in such environments in the early years of their careers, and it can be a long time before they learn how to overcome these habits... if at all.

You would be better off teaching students how to write code that is clean, and how to identify the problems in software that usually end up incurring technical debt. Look into books about Clean Code, Refactoring, and Lean Software Development as a starting point as a place to start, and teach students to write unit tests before the implementation code in order to ensure there is a high degree of test coverage. Teach students to recognize duplicated and repetitive patterns within their code, and how to refactor the code to remove such duplication. Help students to understand and apply principles such as SOLID and DRY. Most importantly, do away with this idea that the ability to maintain code is something that is done based solely on the design and implementation of the code, and instead instill a sense of craftsmanship and quality in the production of software from the outset, seeking to refine the code as it is implemented in order to minimize the impact of technical debt and thereby keeping the cost of maintaining software to a minimum over time.

  • I've read your answer with attention, and also your article about "maintainable", and I must say that I almost completely agree with you. I have read a couple of the books you mention, and use - or make people use - principles such as SOLID everyday at work (I am not a teacher btw). But I think your answer is a little bit off-topic. I will edit my question to try to clarify what I am searching for. Commented Apr 28, 2012 at 15:29
  • 1
    You make a good point, but it's also fair to say that one project is more or less maintainable than another. Words ending in -able or -ible can be absolute or relative, and it seems pretty clear that the OP is using it in a relative sense.
    – Caleb
    Commented Apr 28, 2012 at 16:19

I think the best way to learn these sort of skills is by doing code reviews and pair programmings. During code reviews, experienced staff can point out how to make code more maintainable (typically by making it more readable) and justify why certain choices can create more maintainable code.

Pair programming is an even better way to teach this sort of thing, because it gives less experienced staff direct experience in maintaining code with someone who already knows how to do it well.

There are also some great books that you can read about writting clean, maintainable code. Clean Code comes to mind.

It's hard to get this experience through academia since students rarely modify large code bases. Most of these skill will come from learning on the job, and code reviews and pair programming can really facilitate this learning.

  • 1
    Although pair programming is a very good way of learning from more skilled developers, and reading the Robert C. Martin books definitely changed my life, the question was more about a pure academical way of learning: how students could be better prepared before they arrive into the professional world of software development. Commented Apr 28, 2012 at 10:12
  • 1
    -1: @suszterpatt's suggestion sounds a lot better.
    – Jim G.
    Commented Apr 28, 2012 at 19:39

Good code = Less maintenance and Easy to enhance / add features.

Bad code = maintenance nightmare

Basically we have to get the points across to the students that "whenever there is a crappy code in a project, a new developer who is going to join the company because the original author of the code is going to suffer and how the software is impacted."

So one of the best way to teach the student about software maintenance is to show the example of both good code and bad code and ask them to add a feature and then teach them that writing a good code is not only for self satisfaction but for making it easy for the folks who are going to maintain the code.


1) Have a pre-written bad code (e.g) duplicate code , a method say "to calculate the mortgage payment" is written in 9 places in a project.

Ask the student to enhance the feature to "add 1.2% surcharge to all mortgage payments".

Now the student will see the pain of locating and fixing the code in all 9 places. There are many chances he could not locate all 9 places the "mortgage payment" is calculated.

2) Now show the Good code which has this method which calculates the mortgage payment in one and only place. demonstrate to the student that how easy to enhance a well written code and explain him how does it enhance the maintainability of the code/project.

BTW, I loved your approach of exposing the students to maintainability of the software.


@mattmattj: Since there a LOT of answers and the link I posted has some good pointers too I'll add something which hopefully isn't a repetition of the already posted answers.

First, one MUST define "maintainability" - there isn't a single definition accepted by all - similar to that of software architecture. So choose one that you feel is the most important, all encompassing and state it in 3-4 lines at max. Then you can talk about some metrics like - time to recollect/understand your own code (or someone else's), number of WTFs per minute/hour etc. Keep it light (humorous) - that'll make them more receptive to what you have to say after that.

Some exercises (it may sound a bit overlapping with some of the responses, please forgive that)

Split the class in two - give one section a simple coding assignment that needs to be done in 1-2 days. Max. Hard deadline. They have to get the work done under all circumstances - guideline - "working code" as they deem fit. For the other group of students the same assignment but with a list of (naming) conventions and some guidelines about design and how points will be deducted if not followed. This is NOT cheating, even if it sounds like it ;) Now have them swap the codes i.e. group 1 now works on what group 2 did and vice versa. Now suggest a modification to original coding assignment and ask them to do it in the same time frame. Reconvene and ask them how easy/difficult it was and open the floor to discussions/opinions. The point will definitely hit home - high chances 50% of the class would be happy and found it easy and 50% found it difficult. You may also ask them to work on their own thing after 3 weeks and see if they can do it in 1 day ;)

(A good twist is you writing the same piece of code in a convoluted manner and giving to the class for modification along with their own)

Here's where you lay the foundation of maintainability - every line of code modified/updated costs the company money. The easier it is to read and recollect code the better/faster the modification that would help decrease time to market. Very important in today's fast paced technological space. Maintainability is the key to efficient evolution of systems.

It's important to understand the difference between greenfield and brownfield development - not every project or system would be created from scratch (it's rather hard to find or be part of "from scratch" projects). Explaining that the field is "inherently" brown and you must spend time shaping it as you go along with eventual phase out when it grows "out of hand" (only possible when the drift is too much and 'unmaintainable'). The sooner they accept that the better. This is difficult since programming is inherently creative but enhancing someone else's code isn't perceived as such - twist it around. Creativity there is the ability to understand the code and then apply "your" creativity to enhance it - if better maintained you'll be able to more creatively enhance it in the future.

Feel free to refer to the spaghetti analogy in the above link...hope this helps hit some points home. The other answers help fill in the gaps and should help you with the teaching! Best of luck!

  • @Downvoter - please leave a comment to increase chances of improving the post :)
    – PhD
    Commented May 3, 2012 at 3:03

Not the answer you're looking for? Browse other questions tagged or ask your own question.