Code understanding, reverse engineering, best concepts and tools. Java

Question

One of most demanding tasks for any programmer, architect is understanding other's code.

For example, I am contractor, hired to rescue some project very quickly. Fix bugs, plan global refactoring and therefore I need most efficient way to understand the code. What is the list of concepts, their priority and best tools for this?

Of what I know: reverse code engineering to create object models (creating of diagram per package is not so convenient), create sequence diagrams (the tool connects in debug mode to the system and generates diagrams from runtime). Some visualizing techniques, using some tools to work not just with .java but also with e.g. JPA implementors like Hibernate. Generate diagram for not all the codebase, but add some class and then classes used by it.

Is Sparx Enterprise Architect state of the art in reverse engineering or far from that? Any other better tools? Ideally would be that tool makes me understand the code as if I wrote it myself :)

Answer 1

The book Object-Oriented Reengineering Patterns deals with this in detail. Unfortunately there is no silver bullet attached :-)

However, it lists a lot of useful techniques for taking over legacy code. In brief

• interview at least some of the original developers (if they are still around) about
  • development history: phases, releases
  • current state of affairs
  • team social structure, politics, dynamics: when and why did people join and leave
  • bugs: typical, easiest, hardest
  • code quality: cleanest / ugliest parts
  • configuration data: form, content and usage
  • unit / integration / manual / ... test cases and data
  • SCM branch structure and usage
  • documentation: what is documented where, is it up to date
  • contact persons for external interfaces
• Watch developers / users during demo to find
  • main features
  • typical use cases
  • usage anecdotes
  • good / bad, missing / superfluous functionality
• "read all the code in one hour"
  • get high level view of class hierarchies, interfaces
  • take multiple sessions if needed
  • identify large structures (these often contain important functionality)
  • look for design patterns
  • check comments (they can reveal a lot, but may be also misleading)
• skim documentation (if there is any)
  • just record the availability of specific types of docs e.g. specification, UML diagram, Wiki, Javadoc etc.
  • is it useful and why (not)
  • is it up to date

Answer 2

By far the most important tools are your ears, your tongue and your larynx. Ask the people who are familiar with the code - they'll be able to help you understand its general architecture much better than any software tools.

Automatically reverse-engineered complete UML models are generally nearly useless because they cannot distinguish between important abstractions and implementation details - which is the whole point of such models.

Software tools are more useful to answer very specific questions when you are investigating details, such as "where is this method called from?" or "what classes implement this interface" - any good IDE will be able to do that. Debuggers can help too - placing breakpoints at keypoints of the code and looking at the call stack when they're hit is often very enlightening.

Answer 3

Just to elaborate on Michaels mentioning of good IDE's which can help you:

I use the following Eclipse facilities a lot:

• Shift-F2 when the cursor is placed in an identifier brings up the Javadoc for that identifier, if any. Good for navigating.
• Hovering the mouse over an identifier brings up a box with the Javadoc in it, if any. Good for reminding when writing e.g. a method call.
• The Declaration view shows the source where the keyword where the cursor is placed, is defined. This is updated when the cursor moved.
• F3 goes to the definition of the current identifier.
• Ctrl-T on an identifier shows all subclasses and implementations in a popup. Very useful when working on interfaces.
• F4 on an identifier brings up the implementation hierarchy of that identifier in a panel, which can be navigated. Very useful to learn how things are connected. This includes both classes and interfaces.

Answer 4

EclipseUML Omondo is the best Java reverse engineering tool. It reverse all the java code, all packages and even class interaction with interface if not in the same package. Just amazing. You can also reverse: - .class - hibernate annotations - JPA annotations

What I like with this tool is that my code is clean because all the model information is saved into an xmi format and not as tag in my code. You can also create small documentation inside each existing package using diagrams as a view of the model. Just marvelous and respecting the official uml 2.2 specification. The only problem is that it is really too expensive so the price is a stop for me !!