Some months ago, I did some redocumentation work of a mid-sized legacy system (~1 Mio. LOC). Among other things, the system lacked consistency because there were many terms that were differently interpreted from different teams over time, e. g. there were at least three different usages of the name “model” in class names: UI Model, Data Transfer Model, Database Model.
It’s hard to understand such a software system when there is so much ambiguity in naming. It really overloads your brain to quickly grasp the main ideas of such a system. But unfortunately, you can’t immediately change such an old system to the way you'd like it to be. What I did instead was to document that developers should be cautious when they come to a class with “model” in its name. But just writing down the characteristics of those different models wasn’t enough for me. I wanted to show developers directly in the documentation how those different types of models could be identified and which one they were. So I created a Code Inventory.
I want to show you the basic ideas and how you can do it yourself. But first, let’s define the term “Code Inventory”:
A Code Inventory is a listing of the concepts your software system is made of.
In a Code Inventory, you can list all kinds of concepts: your controllers, your REST resources or your Data Access Objects – anything that you can systematically identify by syntax or structure. A Code Inventory helps you to keep track of the things that are already implemented in the software. Further, you can document all the little shortcomings that you plan to improve in the future – a great way to manage technical debt!
How can you build a Code Inventory? In reality, you create an inventory by counting the different items on the shelf. In virtuality, you count the items in your source code that represent the concepts.
Automated Inventory Creation
Here's the nice thing: for Java software systems, you don’t need to manually count your source code items that belong to a concept anymore. There is this nice static analysis open-source tool, jQAssistant, that can do it for you. Just tell it what to find in your code by describing the concepts and it will give you the answer! jQAssistant scans your complete code base and stores a big graph of it in the graph database Neo4j. The graph of your software can then be queried by using the intuitive-to-use Cypher query language.
MATCH (t:Type)-[:ANNOTATED_BY]->()-[:OF_TYPE]->(a:Type) WHERE a.fqn="javax.persistence.Entity" SET t:Jpa:Entity RETURN t AS JpaEntity
This will mark and list all the JPA Entities that exist in the source code:
Because I also want to document that I have those Entities already, I can save that query in my documentation – a plain AsciiDoc file. jQAssistant will then execute this query on every build of my software and I can find the query’s results in a separate report.
Documentation and Code Tied Together
Here is another nice thing: A few days ago, jQAssistant announced that it will create an HTML documentation out of the AsciiDoc file, including the query’s result:
This enables you to show readers of your documentation not only the concepts or characteristics of your code items but also where you can find them directly in the documentation as well!
And here is another one of the newest things: jQAssistant can even create diagrams based on the query’s result, too, using PlantUML/GraphViz:
No more time wasted creating out-of-date UML diagrams. jQAssistant creates them directly from your code using the query you use in your documentation. This new feature connects documentation and code bidirectional.
With jQAssistant, you can now create a Code Inventory of your software system automatically. The documentation never goes out of date because the actual code is in your documentation.
PS: Thanks, Dirk! That’s really a great addition to jQAssistant!