This article was originally published in 97 Things Every Software Architect Should Know.
As a software developers and architects we want to know how good the software is we are developing. Its quality has an obvious external aspect, the software should be of value to its users, but there is also a more elusive internal aspect to quality, to do with the clarity of the design, the ease with which we can understand, maintain, and extend the software. When pressed for a definition, this is where we usually end up saying “I know it when I see it.” But how can we see quality?
In an architecture diagram little boxes represent entire systems and lines between them can mean anything: a dependency, the flow of data, or a shared resource such as a bus. These diagrams are a 30.000ft view, like a landscape seen from a plane. Typically the only other view available is the source code, which is comparable to a ground level view. Both views fail to convey much information about the quality of the software, one is too high level and the other provides so much information that we cannot see structure. Clearly, what is missing is a view in between, a 1000ft view.
This 1000ft view would provide information at the right level. It aggregates large amounts of data and multiple metrics, such as method count, class fan out, or cyclomatic complexity. The actual view very much depends on a specific aspect of quality. It can be a visual representation of a dependency graph, a bar chart that shows metrics at a class level, or a sophisticated polymetric view that correlates multiple input values.
Manually creating such views and keeping them in sync with the software is a hopeless endeavour. We need tools that create these views from the only true source, the source code. For some views, a design structure matrix for example, commercial tools exists but it is also surprisingly easy to create specialised views by combining small tools that extract data and metrics with generic visualisation packages. A simple example would be to load the output from checkstyle, which is essentially a set of metrics on the class and method level, into a spreadsheet to render charts. The same metrics could also be shown as a treemap using the InfoViz toolkit. A great tool to render complex dependency graphs is GraphViz.
Once a suitable view is available software quality becomes a little less subjective. It is possible to compare the software under development with a handful of similar systems. Comparing different revisions of the same system will give an indication of trends while comparing views of different subsystems can highlight outliers. Even with just a single diagram we can rely on our ability to spot patterns and perceive aesthetics. A well-balanced tree probably represents a successful class hierarchy, a harmonious set of boxes might show code that is organised into appropriately sized classes. Most of the time a very simple relationship holds: If it looks good it probably is good.