Tools and best practices to understand somebody else's code

Question

Hello everyone.

Sometimes one needs to dig into someone else's code, understand it and maybe refactor/fix it. So I'm wondering what tools/practices do you use to do that? It's not about any specific language or platform, rather some advises in general.
I myself find it very useful to run the code in question under debugger (if it is possible of course), set breakpoints and step through the code.
Also I've used a few UML tools with reverse engineering features to see the big picture. Visualization works pretty well for me.
There's one tool, that I've used quite a bit: Understand. It's not a UML tool, but it has a bunch of visualizations for the code. For instance control flow diagram for a function, which is not part of UML, but sometimes it's very useful.
I've heard that sometimes people write tests for the code they want to learn, but it hasn't been working for me. Sometimes the code I want to understand is not very testable.
There are other tools, like profilers, dependency checkers, loggers etc. Does anybody use it with any success? And how?
What the first thing use start with? What's the next?

Answer 1

Are you looking for high-level structure, like modules, namespaces, and class design? Or are you trying to understand the internals of the classes, e.g. how specific lines of code work? Those are two different kinds of analysis tools.

Answer 2

I have been in this situation before... It's not much fun. The best way I've found is to write unit-tests to cover the areas that are going to change. Even if tests already exist, this gives you experience with both the api and behavior of the code you intend to refactor. Additionally, you gain more tests to verify the replacement implementation.

Answer 3

Typically, I divide these kinds of requests into 2 camps:

1. Fix the bug, not the whole code. In this case, I'd tend to read the code and see if I can easily put in the fix without making major significant changes, e.g. adding 5 lines of code or less. This is where the changes made are like a surgical strike that does minimal impact to achieve the desired result.

2. Tear down the code and put up much better stuff. In this case, there isn't a good little way to do the change or there are lots of little changes that want to get bundled up into a mini-project where digesting all the code is needed and this isn't a quick minor change. Taking an ASP site and putting it into the latest .Net framework would be an example here.

Determining which kind of change something is requires a bit of practice and experience understanding what someone else may call, "One more thing if you could..." that may be a huge deal but they don't see it that way,e.g. could we add a little module that records any error and sends me an e-mail when something bad happens that may not be so easy after all the other requirements get worked out like what if the code can't send a mail message what should it do.

Answer 4

Sort of platform specific, but ReSharper is great for teasing out the hidden meaning of .NET code. I love the "Find Usages Advanced" feature where you can look for sets, gets, implementations etc...

Answer 5

Do check out nWire. It is an Eclipse plugin, currently for Java & PHP, which analyzes your code and offers code exploration, visualization and search tools. The tool is about understanding the associations in your code: class hierarchies, invocations, instantiations and pretty much everything else.

I find it very useful for digging into piles of code (BTW, for me, even my own code becomes alienated after a couple of months of not touching it).