On Architecture: The dubious joy of system architecture revision

Lately, I have had the rather dubious pleasure of reviewing some of our existing systems and find a plan for improving the maintainability of these systems. I have not done much work like this before, and I came in unprepared for the experience.

Most systems that have been maintained for a number of years have a maddening complexity, especially if they include a range of technological elements. Cramming the systems into my head completely enough to not make recommendations that are counter productive when they are faced with reality requires me to digest a lot of detailed information from many sources.

Here is a description of a typical day of architecture review: 1. Get up late (due to reasons that will become obvious). 2. shift around documentation, code and notes for a few hours, while consciously and guiltily thinking about definitely non-job-related issues. Being disturbed by emails inquiries every fifteen minutes. 3. A one to two hour interview with one of the experts on the system, which usually ends with me claiming that they all hate me and want me to have a heart attack (I really could handle that better, my sincere apologies to those who have had to suffer through it). 4. Late lunch – the paper shuffling + interview made me forget to do lunch at normal hours. 5. Actually burrowing down into the documentation, code and notes, while still being disturbed by an urgent email every fifteen minutes, so the house of cards that is my understanding of the system collapses into a sorry mess. 6. Writing a few lines in my final report, deleting them, writing them again, screaming loud in frustration with the insufficient expressiveness of the written word and UML diagram (luckily, by this time, everyone has left work). 7. Find some lame excuse to go out with friends and get hammered. 8. Go to bed drunk and exhausted by 2 am, and reading printouts for another two hours before going to sleep.

I think the distracted, messy, unconcentrated process is necessary for me to actually digest and process the information. I am always able to come up with a plan for improving the system, although I usually find it extremely hard to express it in the report, and I underestimate how long it will take. By the time I am done, I am a depressed, alcoholized, distracted wreck. But the recipients are usually happy. I am not sure I’m cut out for this.

There must be a better way. If I find out, you will be the first to know.

About Johannes Brodwall

Johannes is Principal Software Engineer in SopraSteria. In his spare time he likes to coach teams and developers on better coding, collaboration, planning and product understanding.
This entry was posted in Software Development. Bookmark the permalink.
  • I'm happy to see that there are people who are concerned about the maintainability of systems. It seems like most people don't care, or they don't have the time right now, or they believe that their code is as easy to understand for other developers as it is for them.

    I very rarely experience that developers take this aspect into account when they produce something. Maybe not so strange though, as it takes a lot more effort and time (and experience and perhaps some talent) than just making it work. As long as you are under some time pressure, and your manager doesn't ask for it (and probably nobody else either), why should you bother?

    I think the only way to prevent systems from becoming a mess is to have clear requirements for maintainability, so that it is clear that the system is not finished until these requirements are met.

  • I totally agree

  • I’m happy to see that there are people who are concerned about the maintainability of systems. It seems like most people don’t care, or they don’t have the time right now, or they believe that their code is as easy to understand for other developers as it is for them.

    I very rarely experience that developers take this aspect into account when they produce something. Maybe not so strange though, as it takes a lot more effort and time (and experience and perhaps some talent) than just making it work. As long as you are under some time pressure, and your manager doesn’t ask for it (and probably nobody else either), why should you bother?

    I think the only way to prevent systems from becoming a mess is to have clear requirements for maintainability, so that it is clear that the system is not finished until these requirements are met.

  • I totally agree

  • Personally, I get afraid when I hear the phrase “design for maintainability”. I hear that “if we just worked harder, we wouldn't get into these troubles”, and “why can't you do it right the first time.” Maybe we are in agreement, but I am still looking for some better method than blaming those who've done the best job the could do under the circumstances with the results.

    All requirements should have clear (ideally quantifiable, but probably not always quantified) business value. When the customer is knocking at the door, when the software is getting more and more delayed, how can we value maintainability?

    Dark mood today. Sorry.

  • Personally, I get afraid when I hear the phrase “design for maintainability”. I hear that “if we just worked harder, we wouldn’t get into these troubles”, and “why can’t you do it right the first time.” Maybe we are in agreement, but I am still looking for some better method than blaming those who’ve done the best job the could do under the circumstances with the results.

    All requirements should have clear (ideally quantifiable, but probably not always quantified) business value. When the customer is knocking at the door, when the software is getting more and more delayed, how can we value maintainability?

    Dark mood today. Sorry.

  • You are pointing out the two main problems here. I'll respond to the last one first: the customer doesn't ask for it and is in a hurry. However, the customer really needs it, even though they are not aware of this fact. I have seen several reports estimating that “two-thirds of a software system's lifetime cost involves maintenance” (quote taken from http://en.wikipedia.org/wiki/Software_maintenance). So it is really in the interest of the customer that this job is as easy as possible, since it is usually the customer who has to pay for it.

    The company creating the software, however, usually doesn't have much interest in this, because they will mostly get paid in full for any job they do after delivery, and the maintainability of their creation does not effect their chances of getting a contract for the maintenance.

    So the only victim here is the customer, who will have to pay more for changes (well, and the poor people who are assigned to the maintenance job, and they are quite often not those who developed it).

    The second problem is the quantification of maintainability. That is not easy to do, but we all clearly see the difference between code that is easy to change, and code that we don't dear to touch. This tells me that it should be possible to test this somehow.

    My main point, however, is this:
    the customer must demand and control that the system they buy is reasonably maintainable. Nobody else will do it.

  • You are pointing out the two main problems here. I’ll respond to the last one first: the customer doesn’t ask for it and is in a hurry. However, the customer really needs it, even though they are not aware of this fact. I have seen several reports estimating that “two-thirds of a software system’s lifetime cost involves maintenance” (quote taken from http://en.wikipedia.org/wiki/Software_maintenance). So it is really in the interest of the customer that this job is as easy as possible, since it is usually the customer who has to pay for it.

    The company creating the software, however, usually doesn’t have much interest in this, because they will mostly get paid in full for any job they do after delivery, and the maintainability of their creation does not effect their chances of getting a contract for the maintenance.

    So the only victim here is the customer, who will have to pay more for changes (well, and the poor people who are assigned to the maintenance job, and they are quite often not those who developed it).

    The second problem is the quantification of maintainability. That is not easy to do, but we all clearly see the difference between code that is easy to change, and code that we don’t dear to touch. This tells me that it should be possible to test this somehow.

    My main point, however, is this:
    the customer must demand and control that the system they buy is reasonably maintainable. Nobody else will do it.

  • My main point, however, is this:
    the customer must demand and control that the system they buy is reasonably maintainable. Nobody else will do it.

    It is true that nobody else will do demand maintainability. But is the customer inclined and informed enough to do it? Willing to pay for it?

    And if the customer is willing to pay for it, are we able to reliably deliver it?

    And a last question: Am I being defeatist?

  • My main point, however, is this:
    the customer must demand and control that the system they buy is reasonably maintainable. Nobody else will do it.

    It is true that nobody else will do demand maintainability. But is the customer inclined and informed enough to do it? Willing to pay for it?

    And if the customer is willing to pay for it, are we able to reliably deliver it?

    And a last question: Am I being defeatist?

  • The customers must become aware of their need, and that will probably not happen tomorrow. However, I wouldn't be surprised if a customer signing a contract for a tailor made system tomorrow included some sentences about automated tests. I guess it's a matter of how much attention things get.

    Automated tests improve maintainability, so if customers start demanding that, then one piece is in place. For this part, we also have good measures.

    I think customers are willing to pay for it if they understand that it is good economy. The customer will probably need to hire people to check for them, just like they often hire people to check the architecture, the project management and more.

    Are we able to reliably deliver it? I don't know. Are we able to reliably deliver good architecture? There are at least some best practices one can state (like the negation of these tips: http://thc.org/root/phun/unmaintain.html).

    Even though it is difficult to standardize tests for this, one can try to make some changes and see how difficult it is. If it is hard, you will see what makes it hard, and hopefully whether it really needs to be like that.

    Are you being defeatist? I agree that the road is really long, but I don't think it is endless.

    Do you?

  • Hi, Christian

    Any road worth walking is endless. :-)

    I agree that automated test and all the things I have preached at your previous place of employer can help improve maintainability if used well. And I think you're right that it can be sold, too.

    On a further note, like most interesting characteristics, it is impossible to measure maintainability without putting a system into production and improving it incrementally. So incremental deliveries might be a good tool for selling techniques for maintainability.

    As Robert Glass says (in Facts and Fallacies about Software Development): The maintainance period is not the problem, it is the solution.

  • The customers must become aware of their need, and that will probably not happen tomorrow. However, I wouldn’t be surprised if a customer signing a contract for a tailor made system tomorrow included some sentences about automated tests. I guess it’s a matter of how much attention things get.

    Automated tests improve maintainability, so if customers start demanding that, then one piece is in place. For this part, we also have good measures.

    I think customers are willing to pay for it if they understand that it is good economy. The customer will probably need to hire people to check for them, just like they often hire people to check the architecture, the project management and more.

    Are we able to reliably deliver it? I don’t know. Are we able to reliably deliver good architecture? There are at least some best practices one can state (like the negation of these tips: http://thc.org/root/phun/unmaintain.html).

    Even though it is difficult to standardize tests for this, one can try to make some changes and see how difficult it is. If it is hard, you will see what makes it hard, and hopefully whether it really needs to be like that.

    Are you being defeatist? I agree that the road is really long, but I don’t think it is endless.

    Do you?

  • Hi, Christian

    Any road worth walking is endless. :-)

    I agree that automated test and all the things I have preached at your previous place of employer can help improve maintainability if used well. And I think you’re right that it can be sold, too.

    On a further note, like most interesting characteristics, it is impossible to measure maintainability without putting a system into production and improving it incrementally. So incremental deliveries might be a good tool for selling techniques for maintainability.

    As Robert Glass says (in Facts and Fallacies about Software Development): The maintainance period is not the problem, it is the solution.

  • Kukenspeil

    Really what you want to do instead of drinking until kl2 is drink util kl3 and then get a kebob. Only then will you be able to deal with the mess of those BBS projects.

  • Kukenspeil

    Really what you want to do instead of drinking until kl2 is drink util kl3 and then get a kebob. Only then will you be able to deal with the mess of those BBS projects.