How should I visualize the structure of my code?
I have an application written in Java. In is stored in several files. It uses different classes with different methods. The code is big and complicated. I think it would be easier to understand the code if I have a graphical model of the code (some kind of directed graph). Are there some standard methods for visualization of code. I am thinking about usage of UML (not sure it is a correct choice). Can anybody recommend me something?
ADDED:
I consider two possibilities:
- Creating the graph by hands (explicitly).
- Creating graph in an automatic way. For example to use some tools that read the available code and generate some graph describing the structure of the code.
ADDED 2:
It would be nice to have something for free.
Answer
I tried using a number of UML tools and found that the reverse-engineering capabilities in most UML tools were not helpful for understanding code. They focus on designing needs and reverse-engineering capabilities often just ends up showing huge pictures of lots of useless information. When I was working on the Microsoft Office codebase, I found using a pen-and-paper more helpful that the typical design/modelling tools.
You typically want to think about doing this in a number of ways:
- Use your brain: Someone else mentioned it - there is no substitute to actually trying to understand a code base. You might need to take notes down and refer back to it later. Can tools help? Definitely. But don't expect them to do most of the work for you.
- Find documentation and talk to co-workers: There is no better way than having some source describe the main concepts in a codebase. If you can find someone to help you, take a pen and paper, go to him and take lots of notes. How much to bug the other person? In the beginning - as much as is practical for your work, but no amount is too little.
- Think about tools: If you are new to a part of a project - you are going to be spending a significant amount of time understanding the code, so see how much help you can get automatically. There are good tools and bad tools. Try to figure out which tools have capabilities that might be helpful for you first. As I mentioned above, the average UML tool focuses more on modeling and does not seem to not be the right fit for you.
- Time vs Cost: Sure, free is great. But if a free tool is not being used by many people - it might be that the tool does not work. There are many tools that were create just as an exploration of what could be done, but are not really helpful and therefore just made available for free in hopes that someone else will adopt it. Another way to think about it, decide how much your time is worth - it might make sense to spend a day or two to get a tool to work for you.
Once there, keep these in mind when going trying to understand the project:
- The Mile High View: A layered architectural diagram can be really helpful to know how the main concepts in a project are related to one another. Tools like Lattix and Architexa can be really helpful here.
- The Core: Try to figure out how the code works with regards to the main concepts. Class diagrams are exceptionally useful here. Pen-and-paper works often enough here, but tools can not only speed up the process but also help you save and share such diagrams. I think AgileJ and Architexa are your best bets here, but your average UML tool can often be good enough.
- Key Use Cases: I would suggest tracing atleast one key use case for your app. You likely can get the most important use cases from anyone on your team, and stepping through it will be really helpful. Most IDE's are really helpful here. If you try drawing them, then sequence diagrams arethe most appropriate. For tools here I think MaintainJ, JDeveloper and Architexa are your best bets here.
Note: I am the founder of Architexa - we build tools to help you understand and document Java code, but I have tried to be unbiased above. My intention is to suggest tools and options given that this is what I focused on as part of my PhD.