It is really frustrating to find that every other open source project's source code and documentation etc., follows slightly or hugely different directory structure and naming conventions.

  1. How do I quickly orient my self to the directory/naming conventions?
  2. Get to the overall architecture of the app without going through a bunch of source code files?
  3. How do I make reaching to the relevant code (that I am interested in) quicker?

The best way is to download the whole project under your favorite IDE and use the IDE tools to gain a first overview.

For the Apache Software Foundation for example, they have just one huge Subversion root from which you can pull any single project in a few clicks using Eclipse. This creates a project in your workspace and you can use all the powerful tools of Eclipse to understand the class hierarchy, navigate (Ctrl/click) from one class to the next or just search artefacts in files. The same holds true for Intellij or Netbeans of course.

For github, just add a git plugin to Eclipse and do the same. At Sourceforge they use Subversion as well and used to rely on CVS, but the same will apply.

It seems like a lot of work but believe me it isn't. This strategy will also allow you to understand the various ways to build and architecture OSS (Maven, Hudson/Jenkins, Ant, make/nmake etc...).

Once you've done it once, it's much easier the second time and you'll find out it's always the same process.

Your developer skills will get a boost from taking this option seriously.

  1. Directory and naming conventions will become clear when you start reading the source code
  2. Documentation should speak about it. Some projects use design patterns extensively with many callbacks, delegates and such. Prior experience and knowledge in these areas will definitely make it easier to grasp the overall architecture of the project. Then, there will be a developer mailing list per project(some may have more than one)
  3. If you use Emacs or Vim, use etags/ctags in combination with cscope. I think Eclipse, Netbeans, Anjuta and such have similar features too.

IMHO, spending some time to read through the sources, documentation, mailing list archives in order to understand any project, whether open source or not should be OK. After all, many man hours of work has been put in there, and understanding it all should take some time. You might have a different opinion here.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.