The use of UML in software maintenance and its perceived benefits and hurdles

UML is widely used to model software. It’s been studied extensively, so its effectiveness is well-known… for greenfield projects. Unfortunately, most projects are actually brownfield. Fernández-Sáez, Chaudron, and Genero conducted interviews at a multinational company to understand how UML is used in software maintenance.

A common issue with studies about the effectiveness of software engineering practices is that they’re conducted with students or open source projects. We can learn a thing or two from these studies, but it’s never really clear how well the findings apply to software development in commercial settings.

This is especially true for the effectiveness of UML, which has mostly been studied for projects in which a system is built from scratch, even though it’s generally used in ongoing maintenance projects.

We therefore need case studies to understand how effective UML is in practice.

The authors collected data at the ICT department of a multinational transport company in Western Europe. The department has been around since the 60s, so it’s got plenty of systems to maintain.

Semi-structured interviews were conducted with 37 of the department’s employees. Six interviews were discarded, because the employees weren’t assigned to software maintenance projects. The remaining 31 interviews were coded, grouped, and analysed to obtain a grounded theory.

Many of the journal paper’s 65 pages are dedicated to summarising findings from the interviews and visualising these findings in various diagrams. I won’t go into those here, but please do have a look at the original paper if you want to learn more about the software maintenance process and surrounding context.

Projects typically make use of UML to communicate certain aspects of a system’s design to stakeholders, which include analysts, developers, project managers, testers, and business stakeholders.

These stakeholders typically use UML for different purposes and thus require different views: there’s no such thing as a single, perfect “one-size-fits-all” model that covers everyone’s use cases. Unfortunately, modern tooling doesn’t provide any support yet for creating multiple views from a single model.

Informal notation

UML notation is used rather loosely. Most only use a subset of the notation and may even include non-standard notation. Interviewees cite a number of reasons for this:

• When models are used as documentation, they need to be understandable to all audiences, which includes people in non-technical roles (e.g. project managers and business stakeholders). More advanced UML features therefore cannot be used in such models.

• Detailed features of UML have the annoying tendency to change over versions of the standard. By keeping models basic and high-level, such features can be avoided and models become less cumbersome to maintain.

• Since UML is primarily used to communicate the overall system design or some design intent, details generally don’t matter very much. Instead, producers of documentation prefer “freestyling” over adherence to standards if it helps them convey ideas more easily.

Reverse engineering

Many UML (CASE) tools are able to extract (“reverse engineer”) diagrams from code. In theory this offers some pretty great benefits:

• It saves a lot of effort, as documentation can be instantly generated from code;

• Since documentation is generated on demand, it is never out of date.

Not all interviewees were aware that reverse engineering of diagrams is possible.

Those who were, say that it doesn’t work very well (side note: Intent probably can be extracted, but you’ll need more than just the code.): key concepts and abstractions and certain types of diagrams (e.g. sequence diagrams) can only be extracted with a lot of manual effort, which kind of beats the purpose of it.

The only use case that appears suitable for reverse engineering is when a programmer needs to understand a relative small part of a system that they are working with.

Overall, developers strongly prefer forward-designed diagrams over reverse-engineered diagrams, as forward-designed diagrams are also better able to convey the idea behind the system’s design.

It’s often believed that creating and maintaining documentation isn’t a very good use of time and money, especially if special UML tooling is needed.

Costs

The main cost factors are not actually related to UML tooling: tools are relatively cheap (side note: Or even free if you use tools like TikZ-UML, PlantUML, draw.io or a whiteboard.) – especially when compared to tool licenses in other engineering disciplines, which can cost up to $100,000 per year.

What can be expensive is training in UML concepts and notations, migrating documentation, and changing processes.

Benefits

Enough about the costs though: let’s talk about the benefits!

The interviewees suggest (side note: A good thing to keep in mind: the findings here are based on grouped responses by interviewees. If you want empirical evidence of these benefits, you’ll need to look elsewhere.) that there may be two types of benefits: process benefits and product quality benefits.

Process benefits include:

• improved communication and fewer misunderstandings, especially across organisational and geographic boundaries;

• better designs before implementation through easier peer-reviewing;

• prevention of knowledge evaporation when a system’s original designers leave the project;

• easier diagnosis of (behavioural) problems in the software.

Improved understanding of the system to be built and ability to monitor whether an implementation conforms to the design may lead to better product quality.

Structural models (like class and component diagrams) are thought to have a positive impact on the structure – and thus maintainability – of the system, whereas behavioural models (like sequence diagrams) also make it easier to diagnose errors.

Documentation is hard to maintain. Using UML may have some benefits over other notations, but there are some pitfalls that should be avoided.

Maintaining documentation

By far the most common “reason” for not maintaining documentation is time pressure: there’s never enough time to do everything. That, and the general misbelief that the second guideline of the Agile Manifesto (“working software over comprehensive documentation”) means that you should not create any documentation.

There are practical hurdles as well:

• Duplicate versions of the same information can often be found in multiple different archiving systems. This makes it harder to find information and verify whether it’s up-to-date;

• It’s often unclear who’s responsible for updating the documentation and when it should be done.

The authors note that there’s also a clear misalignment of incentives for maintaining documentation:

• Newcomers benefit the most from documentation, but you need experienced and knowledgeable people to create it. These experts do not generally benefit from their own documentation, which makes it feel like a waste of time to them.

• Creating documentation is a long-term investment in a project, as it makes maintenance cheaper and easier in the long run. However, initial development and maintenance are rarely paid for by the same organisation. Someone who manages the initial development therefore has little incentive to invest in good documentation.

Using UML in documentation

In addition to the challenges that you may face when introducing UML to a team for the first time, there are two other reasons why some find UML hard to adopt properly:

• Projects often struggle to find the right level of abstraction and level of detail to use in their models, especially since different stakeholders demand different levels of detail. An organisation should set company standards and provide examples to address this issue.

• UML models and the implementation are ideally kept synchronised, but this can be a lot of work. By simply not including implementation-level details in models it becomes a lot easier to keep models and code in sync. Unfortunately this does mean that UML models cannot be used then to learn more about the implementation.

The authors conclude their paper with a list of practical recommendations for those who are involved in modelling and documenting practices.

Purpose of use

Documentation should not be thrown “over the wall”: all stakeholders should be involved, so that the documentation is actually useful for its consumers.

It must therefore be clear whom you are creating your documentation for and why they need it. You must also agree on the level of abstraction and detail to be used in UML models, so that the models convey the right information.

Process

Creating documentation only really starts to become valuable for teams of 6–8 or more people and projects that last longer than a year.

If you want to create documentation, make sure that it’s clear:

• who is responsible for maintaining documentation;

• when documentation must be created or updated;

• how documentation should be maintained.

If an agile approach is used, this can be done by explicitly including documentation in the definition of done.

Tooling

Creating documentation is not a valuable activity in itself. It should be:

• easy to find information within the documentation;

• easy to verify that it’s still up-to-date with the current version of the implementation;

• easy to navigate between documents, so users can explore the system.

Good (UML) tooling can be very helpful here, provided that they’re available from the start of the project, as developers who join the project at a later stage tend to stick with tools and conventions that were used for existing diagrams.

Tooling is best financed centrally rather than on project level so that projects don’t try to circumvent modelling to avoid (ultimately insignificant) tooling costs.

Training

The long-term benefits of using modelling languages like UML should be made clear to developers. UML should also be taught separately from methodology so that people understand that it is not tied to any one methodology like RUP (side note: This paper must have taken ages to write, because I don’t know any company that still uses RUP…).

Finally, maintainers need to taught how to use modelling tools, as really effective use of UML is only possible with advanced modelling tools.

Standardisation and governance

Projects should use the same modelling tools, training, and practices: uniformity makes it easier find and work with documentation and also makes it more likely that similar problems are solved using similar solutions.

Producers and consumers of documents should know and talk to each other: shared ownership will result in documentation that’s more useful and abundant.