Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

When manually inspecting unfamiliar code (to review or modify), I seem to have three options.

  • A top-down read of the code, choosing each next source file by how fundamental the filename seems. I usually end up reading nearly everything. Some files twice.
  • A breadth-first read, where I find and read all of the invoking method with minimal understanding. Then read all the functions that function called, and so on. My mental stack tends to overflow if I make it a few calls deep.
  • A depth-first read, where I step through all the code in a debugger, unsure of whether this will take 8 minutes or 8 hours.

Once I've read enough of the code to have a fairly solid understanding of what it's doing, I often reflect that I've read 80% or more of the codebase, while the fundamental code is 20% or less. I've wasted a lot of time.

What tools are useful for getting a quick grasp of unfamilar code? Are there any tools that can give a "big picture" of the critical code path and allow me to drill down to the details of any one part?

share|improve this question

closed as off-topic by GlenH7, MichaelT, Bart van Ingen Schenau, Ampt, l0b0 Feb 10 '15 at 7:55

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Questions asking us to recommend a tool, library or favorite off-site resource are off-topic for Programmers as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it." – GlenH7, Community, Bart van Ingen Schenau, Ampt, l0b0
If this question can be reworded to fit the rules in the help center, please edit the question.

without grasping the 80% percent you can't understand why the 20% is the fundamental part – ratchet freak Dec 23 '12 at 20:10
@ratchetfreak I wouldn't say that in such absolute terms. A tool could isolate code that's always called, for example. Or only run many stack levels deep. – Drew Dormann Dec 23 '12 at 20:33
up vote 8 down vote accepted

The best thing, of course, is for someone who does know the code base to walk you through it. If that is not an option, then there are some tools that can help you.

  • VisualStudio can automatically generate a UML class diagram of a code base. At the very least it will show you the class hierarchies.
  • Doxygen can be extremely helpful. Even if the code does not have the doxygen-style comments, doxygen can still generate readable documentation, class diagrams, and call graphs, which can be very helpful for finding your way around an unfamiliar code base.

Generally, you also want to be using a full-featured IDE, where you can right-click anything and "go to definition". This can save you lots of time, compared with using grep on lots of files in a complex directory structure.

Another important thing, depending on how long you will have to deal with the code. If there are unit tests, then look through the tests. If there are no tests, start writing them. Form a hypothesis about what a particular class or function does, and write a test to test it. This takes a lot of discipline, but it is a great way to get answers about what's happening in the code.

share|improve this answer
Thanks @Dima. Doxygen is fantastic at handling some of that. (I didn't want to steer the answers by dropping that one tool name that I know of). Kudos on the level-headed "human interaction" component as well. :) – Drew Dormann Dec 23 '12 at 20:25

This is a more drastic approach. This technique may be useful for a project that has many classes that are not organized into meaningful namespaces.

The goal of this exercise is to discover the class relationship. Make a throwaway clone of the project, and then try to put some classes into namespaces. To save time on repeated attempts, use some Regex file processing tools to automate this change.

This will cause a lot of compiler errors. In the process of fixing these errors, one will have a better grasp how these classes depend on each other, and decide what classes could be put into the same namespace.

This technique is useful in that one can apply it even with little understanding of the project's code organization. With this comes the risk that some classes could be misplaced by this technique due to misunderstanding.

share|improve this answer
That's clever. Do you typically do that for many classes or do you save it for when you come across a specific class that's unclear to you? – Drew Dormann Dec 24 '12 at 14:40
@DrewDormann I learned this technique from one of my colleagues when faced with 100s of classes that were not grouped. It is a very first step toward "sorting" the project files, before any refactoring happens. In other words, it is used when everything is still a mess. (Embarassingly, the mess was written by my earlier self.) By sorting the project files into namespaces, it facilitates Doxygen class page generation (by displaying namespace trees) and also speeds up the programmer's comprehension. – rwong Dec 24 '12 at 16:11

Not the answer you're looking for? Browse other questions tagged or ask your own question.