Tips on walking through unfamiliar code or info on tools that help the process?

Question

I would love tips on how to walk unfamiliar code with many objects. Before OOP this was still a difficult thing and I would do it with listings and have tabs and 8 fingers holding my place. With multiple monitors I have advanced my techniques so it's easier but still difficult. Eclipse does a pretty good job with letting you jump to where something is defined and letting you go back.

With objects and constructors I have found it increasingly difficult to figure out what someone else's code is doing especially when multiple constructors are interfacing with 3rd party API's (seems like a cascading shotgun).

I don't know if there are any tools out there that will map out code using a treeview in the order that the code is executed or not. I'm getting by with Eclipse, but it seems like there should be something that helps make it easier.

I'm mainly having to go through Java code at the moment, but I have the same issues with .NET stuff.

Update:

As slim says there are no easy answers. I haven't asked many questions here, but when I have, I am amazed at how fast excellent responses show up. There really isn't one answer to this question. I accepted Marcin Gil's response as the answer, because using Doxygen with Dot quickly generated a series of web pages with graphs and links to the real source code that makes navigating everything a breeze.

The true answer actually includes a little from every response including the excellent hint of using "code comprehension" as a search in Google. I'm glad I decided to ask this. To help me in the future it looks like I've got some work to do looking at tools revealed with the "code comprehension" search. My immediate need was helped tremendously by the doxygen/dot combo. That combo and profiling will give me the results I need. Thanks.

Answer 1

One quick thing that can be done is run Doxygen/Javadoc. Even with undocumented code, it can help give you an overview.

Answer 2

Whenever I inherit a large project, one of the first things I do is go low-tech.

I pull out a notepad & pencil, and just start writing out each step. It's fairly time consuming, but in the end, I am always left with a good knowledge of how things work.

The idea of writing it down helps me commit the steps to memory, and if I'm wondering how a particular step works later on, I can always refer back to my notes.

Answer 3

Not only use doxygen but use dot with it! You can find it in Graphviz package.

When generating a doxygen config for the project mark to generate all graphs available w/use of dot. It will generate call graphs, reverse usage graphs for the project. And if you include source code you will be able to walk through the code directly from those graphs.

Answer 4

Have a read of Diomidis Spinellis's excellent book "Code Reading" (link to web site) for lots of info about approaches and tools.

BTW This book won the 2004 Jolt Software Development Productivity Award.

cheers,

Rob

Answer 5

If you can run the code on your machine and have access to a good profiler (I use and recommend JetBrains dotTrace for .NET code), then profiler output can be very useful for seeing how the code really works. You can start from either the 'root' (main for a client application, initialization code for a service or component) or from the code that is most heavily used, and then follow call paths.

If you combine this with 'following along' in an IDE with good navigation features, you can get a good sense of how the pieces fit together in practice, which is what is really important.

Answer 6

No easy answers here I'm afraid.

I did raised my eyebrows at your phrase "in the order that the code is executed". Although of course things do get executed in a set sequence, that's not a very 'thinking in objects' approach, and it might be getting you into trouble. Better to find the top level objects, work out their roles and responsibilities, and work out the system from there.

This might not be as effective if the code you're reading wasn't written by someone who thinks in objects either -- it's possible to use an OO language to write code that's not very OO.

There are tools that convert code into UML. I have not found any that were helpful to me. Perhaps the expensive commercial ones (Rational Rose?), but I have not tried these. It would probably be more instructive at first to attempt to draw your own UML diagrams as you work through the code.

You sound like someone having trouble wrenching your mind from a procedural paradigm to an object paradigm -- I had a great deal of trouble making that shift too. But I made it eventually.

Answer 7

You might find useful the book "Working effectively with Legacy Code". It's not exactly your case, but probably you can find some interesting tips to tackle non-written-by-you code. You can read a review here.

Answer 8

You can find some tools, tips and articles if you search for "code comprehension" in Google.

Answer 9

A tip I got from listening to a presentation given by Michael Fethers is to write unit tests for the code. By running these tests with different inputs you get an idea on the behavior of the classes.

They are also helpful to assert that behaviour hasn't changed if you change the code.