How do you familiarize with a codebase that has no documentation?

Question

I don't know, I've been told that the previous developers did fine in picking up and heading straight into coding with no major problem. I wonder if I am doing it wrong by requesting my manager for some brief meetings with some senior programmers here. Is it better to be cautious and finish this time sensitive tracker the long way, or rush it to meat the deadline?

Just on the side note, the previous programmers who maintain this app are all gone after less than a year in the company. Don't know if there's any relation in anything.

Answer 1

Which programming language? How big is the code base (1k, 10k, 100k lines?)

In any case, I recommend using Doxygen to create HTML cross-reference that is easy to browse around.

Answer 2

There was a thread about this on Slashdot a year ago. Amidst the usual Slashdot cruft, there are some good answers; maybe someone can extract them here.

Some good ones are stepping through the program with a debugger, Doxygen (of course) (and related tools like ctags/etags/GNU Global), giving up, and a couple of books about exactly this topic: Working Effectively with Legacy Code by Michael Feathers and Code Reading: The Open Source Perspective by Diomidis Spinellis.

And I personally recommend reading The P.G. Wodehouse Method Of Refactoring; if nothing it's at least a fun read!

Answer 3

I would say with lots of testing, if they have setup some sort of unit testing framework then you're good, if not, then you might want to start one. As there's pretty much nothing more frustrating than breaking something while you're trying to fix another thing.

and for reference you might want to check this out, this dude seems to be in a tighter spot than you are:

inherited-a-php-nightmare-where-to-start

Answer 4

If it's small enough to do this (say 10,000 lines or less) I've had a fair degree of success with good old fashoned listings. Print out the code, get some highlighter pens and those coloured post-it flags and go over the listing, scribbling notes, finding references and piecing together the overall structure. Go somewhere quiet to do it and just spend the time to go over the code.

If it's written in something you can use ctags or something similar on, take a laptop so you can search the code.

Answer 5

I've had a couple of jobs like that, where all the programmers had left the company. I'd call that a red flag.

It's probably no coincidence that the project has no documentation, but it's hard to tell if there's a causal relationship there. The truth could be any of the following:

• The programmers left because management didn't allow them to document their work.
• Management asked the programmers to leave because they refused to document their work.
• The programmers left after the project became too difficult to work on, without documentation.

Probably the best way to familiarize yourself with the code is to write tests. Set yourself up with a unit testing tool that produces code-coverage reports. Write tests that exercise all the code. The code-coverage visualization helps you to spot edge cases that you haven't exercised yet. As you go through this process, I guarantee you'll learn a lot about how the code works. And as a side benefit, you'll produce a full unit-test suite.

Getting a tool that generates API docs is another option, other people have mentioned. This kind of documentation is only useful for reference. It's not useful for showing you how or when to best use a given class or method.

Another exercise would be to build UML diagrams for parts of the system. A sequence diagram can be useful even when the code's object-oriented architecture is flawed.

Answer 6

Did you see this question?

The consensus answer there seems to be:
Dive right in and fix a bug. Pick one limited to to a small portion of the codebase. Use the debugger a lot.

Answer 7

Read the unit tests. No unit tests? Write some unit tests.

Answer 8

I agree with Milan Babuškov. It's impossible to give a general answer to this question--you need (at the very least) to specify a language. In every C/C++ program there's a routine called "main" somewhere. But that's not true in a VB app and it's certainly not true in other languages. This sort of question divorced from context is so generic and vague that practically any answer can be fitted to sound correct.

Answer 9

THe first thing I always do (in VisualStudio) is create a class diagram of each project in a solution. That lets me see a graphical representation of what I'm working with.

And for some reason I just go through the major classes with a yellow legal pad and just jot down notes on what talks to what. This seems to work for me. Don't really know why, or why its any better than just reading the code.

Also, if there are confusing bits of code that you don't know how its supposed to work, then run it through the debugger and step through it. I always try to keep the call stack visible so I get a feel for the different code paths.

One last thing (and this might not occur to everyone) is run it through a profiler. You are not necessarily looking for performance numbers, but you are interested in the captured code paths. Its actually very useful for seeing what actually is happening when it runs.