Often when a person is starting to get familiar with a new project, the first thing he wants to see is the documentation. The needs are a bit different depending on what he wants to do with the project, but the common ground is to grasp a high level understanding. The users of the software are typically concerned with how to install and use it. The developers are additionally interested in how it works. The project documentation needs to fulfill many purposes, but the minimum set that any significant program's documentation should answer consists of the following:
- What is it and what problems does it solve
- How to install and use it
- How to build and develop it
- What features will be developed next and how to contribute
Nowadays it's good practise to put all this information in the project's
README.md file. If everything does not fit in there nicely, just include the links to the subpages.
For topic 3, Unified Modeling Language (UML) provides tools to describe software design and architectural blueprints in visual manner. The most commonly used UML diagrams include:
- Class diagrams
- Composite structure diagrams
- Sequence diagrams
- Activity diagrams
- State machine diagrams
These are excellent industry standard tools to quickly convey large amounts of knowledge about program design. But they also have their downsides.
The problem with documentation
Documentation is good and more is better, right? It quickly turns out that it's not so black and white. Documentation is good only when it's up to date. Software changes rapidly and it's hard to keep everything updated. In an ideal world the documentation would be revised every time the software changes. With any non-trivial project containing decent documentation this quickly becomes a nuisance. The documentation may have been written by someone else and the developer needs to read everything just to get to know what needs to be updated. Required documentation changes may take as long or even longer than the source code change and testing. The other quite popular alternative is to skip the documentation updates and accumulate technical debt in form of stale documentation.
A better approach
We have recognized this problem in Java Design Patterns project. Since the project is mainly aimed at architects and developers, it is natural that the documentation contains also UML diagrams. In the first phase we want to provide a class diagram with all the design pattern examples. For a long time we drew them by hand, but obviously after some time most of them were no longer up to date.
This lead us to develop our custom solution to the problem. It's a generator that creates UML diagrams automatically from the source code. The name of the program is UML Reverse Mapper. It consists of two modules: urm-core is a command line tool (Java jar file) and urm-maven is a Maven plugin. Both of them can be used to generate UML diagrams.
The first version of UML Reverse Mapper can generate class diagrams. It supports two alternative presenters: Graphviz and PlantUML. Here are example outputs from Java Design Patterns Abstract Factory and Mediator code examples. They are produced by the PlantUML and Graphviz presenters respectively.
Where to go from here
UML Reverse Mapper is an open source tool released under the permissive Apache License 2.0. In the first stage it can output class diagrams but its extensible architecture enables development of other diagram types too. It has huge potential to solve part of the stale documentation problem that almost all the software projects are experiencing. We hope you find the tool useful. Maybe even enough to contribute in its development.