I'm a decent solo programmer and freelance web developer and I've created some simple back end programs together with a friend.<p>But when it comes to understanding even the most simple open source projects I can't for the life of me understand what's going on. There are so many functions relating to each other, so many classes that I just get lost. I'd probably get lost in everything my friends have written as well if they weren't there to in detail explain their architecture for me.<p>So how do you do you learn this? There are plenty of books and resources on how to program but I've yet to find any on how to read source code.
* Start at obvious entry points: main(...) for standalone apps, exported functions in libraries and top-level handlers for web applications.<p>* Use a debugger and breakpoints for stack traces to understand program flow (if not available, throw an exception in a function of interest or insert print statements for the same effect).<p>* Either use an IDE that allows you to jump to definitions or map the project with grep (e.g.: grep -H 'class ' * > classes.txt) to save time when manually going to the definition (or anything in between, but what's available depends on the language).<p>* Focus: Especially when not used to code reading one can easily get lost trying to understand every single statement at once. Focus on what you want to understand in this reading session and develop a habit of doing the next step towards that goal once you got a good idea of what you are looking at. Perfect understanding is not necessary - if it turns out you missed a crucial part, you can still go back and re-read.<p>* Practice: The more you read and write code, the more proficient you'll become, the more intuition you will develop and thus the faster you'll be when skimming over unknown code.
The simple fact of the matter is that reading code is hard, maybe even impossible in the general case. You <i>can</i> understand code with some amount of effort, but it often boils down to an exercise in reverse engineering.<p>One thing this means is that in any substantial codebase you are never going to understand all of it. You will typically only have time to learn a fraction of the system, so if you are going to proactively explore the codebase, you will need to prioritize. You probably (but not necessarily) want to get a handle on the top-level architecture before digging deep anywhere.<p>My final piece of advice is that I personally find it impossible to understand just about any non-trivial piece of code without running it, and running it multiple times (1). Perhaps even many, many times. You can run under a debugger (single stepping or breakpoints) and this seems to work for many people. I still rely on print statements sprinkled through the code myself, adding and removing them as I run the code in question over and over again as my current point of interest moves from place to place in the code. This might sound scary, but it's not that different from the way you normally debug code.<p>(1) It's entirely possible that the person that wrote the code in the first place also ran it many, many times (testing each small change) as they wrote it. So it's perhaps not unreasonable that you yourself may need to run it many, many times in order to understand it later.
Knowing which source file to start with is important. That depends quite a bit on the language, and the type of software.<p>Hard to make a short summary here, because there's no easy rule of thumb. For example, you could say, for C, "find the main() function first." That doesn't help, though, if the open source project is a library, like pcre.