While reading someones code I usually prefer a bottom up approach ... That is I try to have some familiarity with the classes in the project creating a abstract whole picture of the project then dig down deep inside the code for details.
However most people argue to me that a top down approach i.e. start from the entering point of the program and follow it function by function is better.
Which approach do you suggest and why?
I prefer pragmatic approach You focused learn those parts of the system you need to interact with. So you uncover one piece of puzzle at a time. After some time, you will learn enough to see the big picture.
Of course, if there are any docs or a mentor to introduce you to the code and explain top-level decisions and architecture, it has to be done from the start.
Also following the code execution path from the entry point and learning function by function would be time consuming and ineffective. First, human brain has a limited capacity to store and process information for a particular level of abstraction. If you expect to read through hundreds of functions and remember them (or at least their names and where they are) you will miserably fail.
As experience with studying in other domains not related to programming (for example, foreign languages, operating some machinery, performing a worklflow etc.) shows, it is best if you get first some general background then pick up the pieces you need in the right context. You learn elements you need for your scenarios, understand their use, adopt the technique and finally remember them with relation to situation and your experience. This is by far the best way.
I can provide an analogy. When you learn a foreign language you learn the words and expressions based on their commonality and appearance in certain dialogues and scenarios but certainly not by reading through a dictionary a to z. The same with code.
I'd say that your approach is top-down: getting the "big picture" first is usually referred to as "top-down" whereas bottom-up is "details first".
Both approaches have their merit: it depends on the situation.
For a small codebase I think it's okay to just look through the code as it would execute. For a larger application I like to flit between the two - try to get a big picture, but look at details for interesting bits as you go along.
I find that just reading the code never works well not matter how you do it. I just never get a good understanding of the way the code interacts.
Much better to fix some small bugs in the code and get a real feel for how it works. If theres no bugs to fix then just pick some small thing on the user interface to change (such as the text that is displayed in a list box), then go about changing it.
Your approach is the one that works for me also:
First try to get a high level overview of the codebase. Good documentation helps. Ideally you want to find out about modules and their relationships. Otherwise the task is more difficult - look at the classes and try to visualize how they relate.
Now you flesh out your knowledge of the system bit by bit. Zoom in to one area at a time. It helps if you can make changes to the code. This way you always increase your understanding of the system gradually. Don't rush it.
I used the combined technique on our last project, and it occured to be somewhat sccessful. Study several "execution traces". Given an input you're interested in, look at debug trace and select a function/class in the middle (not top or bottom) that invokes all others that do the particular type of work, for which your input belongs. If the processing involves uses of certain modules, study them as well.
After you've studied major "middle" function, use top-bottom and start from main function. Now you will not only try to see the whole picture, but also understand what every module you encounter stands for and how it's really used. The overall picture obtained will therefore be comprehensive and sound.
Strictly divide-and-conquer while focussing to become able to understand the top-down-model of the code. Insert as many comments as you need to understand. After finishing, try to remove uneccessary comments and share your commented code with those craving to understand.
Meaning: the objective is to understand the semantical meaning from the top: What is which module, which function, which statement doing? For a start registering which are the parts is of the essence. After that, look for the parts that sound (from naming of those parts) as if they are most interesting for whatever you want to understand from the code. Dig down in thoses parts and start by recognizing the single parts (functions/loops/classes/...) again,...
Very much as if you are designing the whole system. Trying to summarize my findings in short, meaningful comments helps me to grasp what I am reading. Trying to improving the readability of the code with my comments helps to focus on the essentials (and actually creates something).
After all you will only be able to look at one line of code at a time, going at it top down helps you to recognize which line you want to read. From that point on understanding of the code improves bottom-up.