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

How projects really work: beautifully marketed and no documentation
In theory there is no difference between theory and practice – in practice there is.

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.

Why it matters

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.

How the study was conducted

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.

What discoveries were made

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.

How UML is used

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:

Reverse engineering

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

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

Those who were, say that it doesn’t work very wellIntent 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.

Costs and benefits

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 cheapOr 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 suggestA 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 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 difficulties

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:

The authors note that there’s also a clear misalignment of incentives for maintaining 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:

Best practices

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:

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:

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 RUPThis 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.

The important bits

  1. Different stakeholders want to see different diagrams with different levels of abstraction and detail
  2. Diagrams with a high level of abstraction which use only basic UML features require less maintenance
  3. UML models are best created before implementation – reverse-engineered diagrams should only be used in select circumstances
  4. Documentation should be easily searchable, so users can find what they want and be sure that the information is up-to-date