How do I understand an open source project code?

Question

I open the source code and it's folder upon folder of infinite files each with infinite lines of code which doesn't make much sense to me because I dont have the context, and half of it uses functions imported from other files just to make it more confusing. Is there any simple way to know the structure of an open source application's code?

Answer 1

Here are some simple steps you can follow:

Make sure you understand what the project is supposed to do

If it's a logging library, I would look at the feature list. Asynchronous logging? Databases? What kind of configuration? If it's a media player, I would look at the GUI, see if it keeps metadata in a database or just plays files, et cetera. Think how you would implement this application. What technologies and libraries would you use? Check your guesses.

Try to make sense of the source tree

I don't know what project you are referring to, but generally open source projects have a fairly reasonable source tree structure. For example, you might see several folders in the root, such as trunk and branches for different branches, docs, bin and src for different kinds of content, and the source code itself, usually split into several packages (libraries, websites, etc).

Internal package names are usually intended to be self-explanatory and in most cases they are (or, at least, the maintainers believe so). For a media player, I would expect to find a folder for the GUI, a folder for the playback engine, a folder for the search engine, et cetera. If the project itself is a reusable library, it's likely that there will be one root folder. If the language the project is written in supports namespaces (packages in Java) and there are more than a couple of source files, it is of a high probability that the physical structure (files and folders) closely matches the logical structure (namespaces and classes).

Head for the docs

After I learn what the project does and of what, roughly, it consists, I head for the developer documentation. Most open source projects would love to have you as a contributor so they keep a Contribution page with a list of current tasks, milestones and contact details (a few examples). If the project is large enough, there should also be at least some developer documentation. If there is, read some high-level overview documents to get an idea of how the beast works before proceeding to the next step.

Get in touch

Most open source projects have some kind of chat space (usually IRC) and/or a mailing list available. If you can't make sense of what the inner workings are by this moment (and even if you can), try to find some developers and ask them a couple of questions (make sure you don't annoy anyone too much though). If you're likely to contribute, indicate this in the conversation so people feel they're not wasting their time.

Finally, if you still don't get it ...

Contribute

This may sound seem like an insane suggestion to someone who doesn't understand the codebase but I found that working on small tasks actually helps me understand large systems. Just pick anything you like from the task list, make sure the module maintainers know you plan to work on a feature, and jump-start implementing it! Of course at first you won't understand much and may follow a wrong approach, but as you mess with the code and change it, you eventually get a degree of understanding, at least in scope of the module you have been working on. When in doubt, seek advise from the fellow developers—people are willing to help you contribute if you show your effort.

Answer 2

The same way you understand closed source code.

You pick a bit at a time till you understand it.

When you do, look at what it uses and what uses it... go on...

Answer 3

If it is an active open source project you should be able to contact the owners/maintainers of the project. Let them know why you are interested in their project and get some suggestions from them on where you could find out more. People working on active projects should be pretty receptive to honest efforts to learn more about their project and even get involved, as long as you make it clear you are willing to put in your share of the effort.

Once you've done this, you should expect that it will take some time, effort, and hard digging to get to the point where you really understand the project.

You might offer to create a "getting started" document or something similar that they could use in the future to help others get on board. That way there's an upside for all of the questions they are answering for you to help you get your mind around the project.

Answer 4

To add to Dan's answer: for me the best way to understand a project is to start working on it, trying to add a feature, if it is an application; a sample project, if it is a library; add a few unit tests, refactor the code to my liking or restructure the source tree - you name it.

All these steps help to develop a feeling where are the core parts, how the different layers interact, what is solid and important and what can be safely ignored for now. Most of the time these changes remain private - they do not have to reach production quality to give you the bits of knowledge.

And maintaining a log of my progress helps to fill the gap in the documentation (which is hardly ever present).

Answer 5

The project should come with some documentation that helps you navigate through it.

If it doesn't then I would be a bit reluctant to adopt it.

Ok, someone will say that I should help the authors and write the missing documentation, but:

• there is no point in releasing code that nobody understand: You could as well release it as closed source
• lack of documentation usually indicates a lack of quality: even the author will have difficulty in solving a bug reported 4 years from now
• documentation encourages contribution from other community members and helps setting a quality standard that others will follow