How to understand Open Source projects/libraries?

Question

There are few open source projects/APIs/libraries that we use in our project (Spring, Struts, iBatis etc.) and I want to understand their design and how they work internally.

What is the best way to understand these projects? Note that I am already using these libraries in my project. And I know the input-output interaction/configurations for these libraries. What I don't understand is how these APIs/libraries work internally.

The problems I face is:

1. Finding the entry class of the library. Is there any way I can know the entry class for the library - something which is kicking the whole API?
2. Tools/Plugins to use in Eclipse to get an overview of the design of the library. Going through each and every class of the library, can be a very daunting task. Is there any tool you would like to recommend which can generate the class diagrams of the API in Eclipse.

Thanks in advance!!

---

UPDATE: I need some inputs on eclipse plugins which can help me in getting an overview/class diagram of the library

Answer 1

Nice question!!!, what I've done, specially in the case of Spring, apart from consulting the Documentation and their API's is to attach the sources of the project to my project on Eclipse, that way I'm able to navigate through the source code, not just the API. Its been quite helpful specially in the case of the Spring-Security project, there were some concepts that I just couldn't understand until I inspected the source code.

That's one of the advantages of using Open Source libraries.

Regards.

Answer 2

Your best bet for those three would be to consult the official documentation (make sure you are looking at the version you are using) or to get a book on the technology.

Answer 3

Most APIs don't have a class with a main method; they're running in the webserver called by the server itself. Unless they're running as their own server, they won't have a main method.

Answer 4

I always use the same strategy for this: I never try to "understand" the code base as a whole, and I usually try to follow the request flow. I read enough of the documentation to determine what is necessary to use the application, and I read that code (Keep all source code loaded in your IDE).

For example, in struts you'll be installing a servlet filter in web.xml. Start reading the filter and follow the path a single request takes through your stack.

Likewise for spring, there are two main entry points, the filter and "getBean", both of which are mentioned real early in the documentation. Read those two.

For both of these cases you'll find one or two classes that represent the "core" of the framework real quickly. Read those really well and let actual use cases & needs drive your further exploration.

Approaching "understanding" of an open source library (or any other code base for that matter) by trying to find all the pieces is usually not a very good way of approaching these things, it will usually just lead nowhere because a lot of these things contain too much code. When following the request flow I find making diagrams can also be quite distracting, it tends to draw attention/focus away from understanding (and since my understanding increases rapidly most of them are out-of-date even before they reach the printer).

Answer 5

Tools like Structure101 (http://www.headwaysoftware.com/products/structure101/index.php), and Lattix (http://www.lattix.com/) let you analyze code and produce architecture diagrams / dependency matrices.

This is not exactly class diagram - the main focus is on layering. So the entry point is usually the topmost layer.

But then again, as I specified above, you will notice that some libs are just a mess, and these tools will not be helpful enough.

See the S101 online demo: http://www.structure101.com/java/ This for example is the Sonar project architecture: http://www.structure101.com/java/tracker/sonar/1.11.1/arch.html