Possible Duplicate:
How do you dive into large code bases?

I have quite a bit of experience with different programming languages and writing small and functional programs for a variety of purposes. My coding skills aren't what I have a problem with. In fact, I've written a decent web application from scratch for my startup.

However, I have trouble jumping into unfamiliar applications. What's the most effective way to approach learning a new program's structure and/or architecture so that I can start attacking the code effectively? Are there useful tools for their respective languages (Python and Java are my two primary languages)? Should I be starting with just looking at function names or documentation? How do you veterans approach this problem?

I find this has to be with minimal help from coworkers or contributors who are already familiar with the application and have better things to do than help me. I'd love to practice this skill in an open source project so any suggestions for starting points (maybe mildly complex) would be great too!

  • First thing I do is to look for IRC rooms with developers/contributors in it :) – nullpotent Nov 26 '11 at 17:59

Your best answer is to find and read the documentation. If there aren't any available and it is open-source project, it is probably not a good idea to use it.

Using a good IDE which allows you to jump to the implementation of the method is also very helpful to dig into the code.

If you want to work out how, where, when the codes are executed, it may be better to run it in debug mode. You can track back the stack call to see the behaviour or bookmark to pause the running application and view the variables.

| improve this answer | |

There is no tool, or a software or a pattern that can understand a complex project and then explain it to you { ;-) YET }.

See, for advanced system you will always need a good documentation to understand what's going under the hood. Or else you will need to sit and apply your time for understanding.

Let's take an example of Plone CMS. Suppose if this didnt offered a documentation, it would be hard for you, me or any experienced developer. You know why ?? Because no two people take the same solution route for a problem. X can develop a system in abc manner while Z can interpret it better in cba manner. So, the point is if you find it hard to understand other's written system, don't panic. It's happening to you and it has happened to everybody.

Solution to understanding complex systems :- This is just one way of doing it.

  1. Track the result. If its a website, track the file that's rendering the output(HTML)
  2. Check for the logic in this file and models it is accessing
  3. Understand the Model and capture the database.

Therefore, always go from the endpoint to the start point. I take this road for complex system but still sometimes i am unable to figure why some did that and so on. But, at the end i understand what was in his mind and why things are developed this way.

NOTE:- One thing i would like to endorse which is just my opinion. Don't study someone else's system for just learning purpose. Have a real requirement or idea, then put that together. The best road to learning is driving your own car.

| improve this answer | |

Algorithm how I usually approach foreign code (look down for a terse version of it in pseudo-code).

The best way to start exploring the foreign system is to read its documentation, especially if special developer documentation (developer manual etc.) is available here. Ask the previous developer to send you any documentation he or she has for the system and appoint a meeting with him/her (if this is feasible) in 1-2 weeks.

While preparing for the meeting study the documentation. If there is no documentation than you may have chances to get a copy of original specifications that were used to implement the system (in big companies these are usually prepared by Program/Project Managers and kept longer, than running documentation).

If your IDE (like VS2010 Ultimate or Eclipse with Plug-ins) support creating architecture diagrams, than try those to get an overview of your system. There is a bunch of special software, like JDepend/NDepend, depending upon your system, which can be useful here.

If you don't get any specification, look at unit tests -- this is in fact a part of the specification as well and already written in the form familiar to you.

During the meeting ask the developer to guide you through the system and ask questions to the parts you don't understand. I usually try to put myself in developer's shoes and see if something seems to be implemented in somewhat strange way: just ask, maybe there are implicit requirements or limitations you should be aware of.

And here is the promised succinct version of the text above.

if (Documentation.Exists()) ReadDocumentation();
else { 
 if (Documentation.Found()) ReadDocumentation();

If (Code.IsDocumentedProperly()) {

If (IDEOfYourChoice.Supports(ArchitectureDiagramms)) ProduceDiagrammsAndStudyThem();

if (Specification.Exists()) ReadSpecification();
else AskPMIfThereIsDocumentationLyingSomewhereAround();


if (Developer.IsAvailable()) AskToGuideYouShortlyThroughTheCode();
else if (User.Any( user => user.IsCompetent(ThisSystem))) AskUserToGuideYouThroughProgramm();

If (System.HasUnitTests()) {
| improve this answer | |
  • Your algorithm has a bug: if the developer asked whether there is documentation somewhere answers "yes", you should also get and read that documentation ;-) – Péter Török Nov 26 '11 at 19:15
  • I added some plain English text and corrected the bug :) – Alexander Galkin Nov 26 '11 at 19:29

I think there's no right answer, but here's my take. I've found the best way to learn a new town is to drive through it and do some shopping and dining. When you get lost, look at the map. So, to apply the analogy, I'd find a specific task to work on, and focus on that task. You'll learn things along the way, and even though it's just one slice through the code, it's a start. Doing more tasks means more slices, and you'll just naturally begin to get the bigger picture.

That's not to say that looking at high level architecture and code documentation isn't useful. It's just more useful when studying it with the context of your particular task.

| improve this answer | |

The most important thing is to see what the program actually do when running. This allows you to get a grasp on what concepts the program presents to the outside world, what data is expected to go in and out, and allow you to mentally model what should be happening inside. If at all possible, have an experienced user demonstrate the program.

Next, you need to have it in buildable and runnable state inside your favorite IDE, so you can use all your familiar tools to investigate and debug code. From there you should be able to skim the source and correlate your current knowledge with the source code. From there, your best bet for learning is to improve the current documentation of the source. (This is not as silly as it sounds - it really helps).

| improve this answer | |