Understanding and modifying large projects

Question

I am a novice programmer and as a part of my project I have to modify a open source tool (written in java) which has hundreds of classes. I have to modify a significant part of it to suit the needs of the project. I have been struggling with it for the last one month trying to read code, trying to find out the functionalities of each class and trying to figure out the pipeline from start to end.

80% of the classes have incomplete/missing documentation. The remaining 20% are those that form the general purpose API for the tool. One month of code reading has just helped me understand the basic architecture. But I have not been able to figure out the exact changes I need to make for my project. One time, I started modifying a part of the code and soon made so many changes that I could no longer remember.

A friend suggested that I try to write down the class hierarchy. Is there a better(standard?) way to do this?

Answer 1

• check in the code in some source code repository (Subversion, CVS, Git, Mercurial...)
• make sure that you can build the project from the source and run it
• if you already have an application that uses this open source tool try removing the binary dependency and introduce project dependency in eclipse or any other IDE. run your code and step through the code that you want to understand
• after every small change commit
• if you have different ideas branch the code

Answer 2

There's a great book called Working Effectively with Legacy Code, by Michael Feathers. There's a shorter article version here.

One of his points is that the best thing you can do is write unit tests for the existing code. This helps you understand where the entry points are and how the code should work. Then it lets you refactor it without worrying that you're going to break it.

From the article linked, the summary of his strategy:

1. Identify change points
2. Find an inflection point
3. Cover the inflection point
   a. Break external dependencies
   b. Break internal dependencies
   c. Write tests
4. Make changes
5. Refactor the covered code.