Hi There! I have recently started working on a new application that is very complex. There is a huge code base developed in a technology that I was not familiar with. Since then, I have been looking forward to learn somebody else’s experience on reading code and, during my research, I bumped into very nice articles here, here, here, and here. As I have had to read a lot of code myself I found the readings instructive as I could relate to many points mentioned in the posts. So I got inspired and decided to express my own opinions on the matter.
Reading code is challenging. In my opinion the most important thing is to understand what is going on in terms of abstractions.
First of all, you have to know what the piece of code you are reading does. The better way to do that is to understand the domain of the application. For example, if you are working on a financial application and you don’t know what an Options contract is, you will have a hard time even understanding what the application is supposed to do.
Second, you have to get the idea behind the implementation: how the code achieves the goal? In order to do that I think there are two approaches: Firstly, if you are very experienced, chances are that you will already have seen some similar way of solving the given problem before and therefore you will pick it up real quick.
The other approach is to find out what is the flow and what are the classes involved. If you are a UML guy you would draw sequence and class diagrams. The way I do that is to find the event that triggers the code (thanks to swingspy I have been able to do that in Swing apps), put a breakpoint there and start debugging. During the process, keep writing the flow and the classes using pencil and paper. Once you are done, start analyzing your notes and draw a nice diagram. After that I usually have a rough understanding of what is going on and who is doing what and when.
I think this very useful because, specially in Object Oriented systems, there is a tendency of going back and forth between superclasses , subclasses, interface implementations etc. It is very easy to get lost or confused.
Finally and most important, you have to be fluent in the vocabulary. By vocabulary I mean components, algorithms and data structures used in the language. For example, it would be very difficult for a person to read code that uses hashtables to solve a problem if this person does not know what it is and how it works. Similarly, if you are working on a Swing project and you have to read code that uses a JTable, you have to understand how it works. If you don’t it is going to take you a lot of time to figure out what is going on and chances are you will miss something and end up adding bugs to the code.
Note: A friend of mine told me that he loves this so called Archeology job: reading a piece of code for hours trying to figure out what the heck was going on in the mind of the programmer that wrote the code. I am giving it a shot and to my amazement, it is quite fun – it’s like playing detective. Thanks Marcus 
Hi Rafael,
Thanks for the mention. I agree with your take in that, knowledge of a domain is essential to understand the context in which the code was written. In fact I feel that it is a kind of a given – after all, without context, all code is a meaningless drivel of vaguely English like words interspersed with symbols
Interesting approach using the pencil and paper to track your classes – one suggestion would be to place break points at various locations and look at the call stack (copy it out if needed). It will give a pretty good picture of all the methods and classes in memory at that point.