Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

A Code Inventory for Legacy Systems

DZone's Guide to

A Code Inventory for Legacy Systems

Tired of having to figure out what the hell that legacy system's documentation is talking about? Check out these awesome open source tools.

· Agile Zone
Free Resource

See how three solutions work together to help your teams have the tools they need to deliver quality software quickly. Brought to you in partnership with CA Technologies

Introduction

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.

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.

So for example, if I want to inventory the concept of JPA Entities (kind of Java’s database objects) in an application (e. g. in the Spring PetClinic project), I can create a query like this:

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:

JpaEntity
org.springframework.samples.petclinic.model.Visit
org.springframework.samples.petclinic.model.Pet
org.springframework.samples.petclinic.model.Specialty
org.springframework.samples.petclinic.model.Vet
org.springframework.samples.petclinic.model.PetType
org.springframework.samples.petclinic.model.Owner

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.

Summary

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.

I find that really awesome! If you find that cool too, take a look at the complete example report or the excellent documentation to get a first impression of what jQAssistant is capable of!

PS: Thanks, Dirk! That’s really a great addition to jQAssistant!

Discover how TDM Is Essential To Achieving Quality At Speed For Agile, DevOps, And Continuous Delivery. Brought to you in partnership with CA Technologies

Topics:
neo4j ,cypher ,code inventory ,agile ,legacy system

Published at DZone with permission of Markus Harrer. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}