I have recently read a question on Stackoverflow whether there are any tools to help understanding Java code. Somebody asked it, because he started to use a pen and a sheet of paper to get the clue of some code given to him. Not uncommon.
But the problem was, that nobody tried to answer the question, instead giving him tips like “learn Java” or “read tutorials”. I think they have misunderstood the question – because there are definitely tools for that:
A good IDE just like Eclipse is one basic tool to understand code. It helps you in various ways:
- It shows the structure of folders and files of the project. You can easily get an overview of everything. Just import the project and have a look what you got.
- It gives you the ability of syntax-highlighting (trivial, I know), but also the ability to format code like your are used to in a second. That helps reading it, even (or especially?) when you have some experience in the language.
- It shows you the JavaDoc comments right away at every position in your code. So you will always have the documentation with you when needed.
- It provides tools such as a debugger, a call-hierarchy view and many more. All this tools will help you to get an understanding of how the code works.
And it can to much more for you. So it’s really worth to get familiar with your IDE.
UML is a widely used standard for modeling and visualizing code. The purpose of UML is simple and exactly what was asked: it should help you to understand code. The strength of UML is the abstraction. You can easily visualize a big architecture without mention any detail at all. On the other hand, you can add any detail you want if it is important for the understanding of the system.
The basics of UML are not hard to learn, a quick look at Wikipedia should be enough to draw a class diagram. But UML is also enough standardized, that it could not only be read by humans, but also by machines – so you can generate it (so called round-tripping)!
Tools like ObjectAid helps you to generate class diagrams as easy as possible. Just install it in your IDE, create a new class diagram and drag all Java classes in it.
- Tests, especially unit tests (e.g. JUnit tests) could be also very useful to understand the code. A good test is something like a additional documentation or a contract on code-level. It exactly defines how a method can be used (e.g. input parameters) and what it should make (that’s what the test is testing ;)). So, if you don’t understand what a method should do and you have tests, take a look at them. And what if you don’t have any tests? Write your own ones! This is a good approach to explore an API in a structured and repeatable way. Whenever you are not sure what the API does, try to create a test about your assumption.
So, what to do if there is a bunch of new code?
- Import the project to your IDE.
- Get an overview of folders, files, packages and so on.
- Explore the code: What’s in the JavaDoc? What types are used? What about the call hierarchy?
- Run the unit tests and try to understand what the methods are doing.
- Try to run the debugger for a test or two.
- Draw or generate a UMl diagram.
I have uploaded some screenshot in the slideshow above for the open-source RSyntaxTextArea library from Fifesoft. But you will also find some good tutorials in the internet for every point mentioned before. Try to get familiar with at least some of the tools.