How to analyze a project

Question

I've been wanting to help out with an open source project for some time now. I want to do this for two main reasons. I am a strong supporter of foss and I want to gain experience.

I've struggled to find a project that I thought I would want to help with. There are many I would like to help with, but they are far to complex for what I would want to start with. However, I recently found a browser, uzbl, which seems like it is complex enough for me to be able to learn from, however simple enough for me to be able to wrap my head around.

It is a simple lightweight browser which uses webkit and gtk.

Now that you are familiar with my positon, here is my question.

What is the best way to go about understanding the code base?

Now I realize this is a subjective question. However, I feel if I have the suggestions of more experienced developers, I may be able to cut down on the wrong turns I make.

Should I familiarize myself with the libraries used first? Or should I look through the core code and concern myself with what goes in under the hood after I have a basic understanding of the global picture?

How do you guys go about understanding the code base of a new project?

Thank you for your time and effort.

Answer 1

First, compile and run it. With many projects, simply accomplishing that task will give you some understanding :-)

Second, it's good to have some problem to solve. Some small task, like fix a minor bug somewhere. Just debug, search for the bug origin, try to fix it. Then run unit tests (if any), see what else you broke with your fix. Investigate that, too.

Then repeat. A dozen of bugs, preferably in different areas, give some better understanding of the codebase.

After that, I usually start wondering around the product, just looking how it works and playing with it. Natural curiosity takes over sooner or later, and I find a feature that interests me. In a "wow, I wonder how it works" kind of way. Then I try to sketch a high-level design for that feature myself. Along the lines of "what would I do if I had to create this feature? Very briefly, just in my mind, no fancy diagrams and whatnot.

In doing so, I inevitably find myself in need to know more about the system: after all, you can't design a fully isolated feature, can you? You'll have to interact with the rest of the system, and you need to know how. So I go into code and find out.

Then, a moment may come when I realize that I really don't know how to design this little part of that feature. I think, and I think, and I think, and I just don't know. So then comes the sweetest part: I go into the code and look how is it designed in the first place. Sometimes I would be disappointed in the project. But more often, I would be disappointed in myself. But that's exactly what's precious: that's how I learn.

Answer 2

I have found two things (in addition to the answer by Fyodor Soikin) that really help. One is getting doxygen to do document everything for me. It makes it a lot easier when I can go through the function declarations, and click the data structure which is supposed to be passed in so I can see all the members it contains (if there is no current documentation you can just set EXTRACT_ALL = YES). I also find it very useful to compile the project with debuggin symbols then run it in gdb so that you can follow it from start to finish.

Answer 3

I would look for their tests first, and look at those. If there aren't tests, I probably wouldn't bother with the project. If there are tests, they should be instructive as to how the software works. Step through the tests in the debugger to understand how the high level components fit together.