Take the 2-minute tour ×

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?
share|improve this question

2 Answers 2

up vote 2 down vote accepted

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.

share|improve this answer
Google code uses svn or hg, not git. –  Tamás Szelei Apr 29 '11 at 8:52
@Tamás Szelei, thx, corrected. I took this project: eclipse-jmx and they are actually hosted on github, although referenced at Google code. –  Alain Pannetier Apr 29 '11 at 9:26
I wish google code had git though :) –  Tamás Szelei Apr 29 '11 at 9:29
@Tamas ... Google is listening to you :) .... see comment 39 on code.google.com/p/support/issues/detail?id=2454 –  explorest Apr 29 '11 at 18:13
that's good to hear, thanks for the heads-up :) –  Tamás Szelei Apr 29 '11 at 18:55
  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.

share|improve this answer

Your Answer


