How to read code
November 20, 2009
Here are a few tips on how to better read and comprehend legacy code
A significant part of a developer's work is to read code written by others (or even code written by yourself whose memories have somewhat faded). Reading code is a skill and there are techniques using which you can improve your ability to read and understand code faster.
Programmers work and think in a language of their own and just like any other language writing and reading are two different aspects and both require its own kind of skills and practice to master. Most programmers when they get into the field, start by writing programs - small ones and then gradually bigger and more complex ones. They have a lot of books and tutorials to help them learn to become a better programmer but mostly from the point of view of writing programs. Reading other people's code happens by mostly by accident and developers are expected to just do it. This isn't something taught in colleges or even discussed much among developers themselves. Developers are supposed to pick it up as they go.
Here are two articles which has shaped my own thinking on the topic.
Programmers work and think in a language of their own and just like any other language writing and reading are two different aspects and both require its own kind of skills and practice to master. Most programmers when they get into the field, start by writing programs - small ones and then gradually bigger and more complex ones. They have a lot of books and tutorials to help them learn to become a better programmer but mostly from the point of view of writing programs. Reading other people's code happens by mostly by accident and developers are expected to just do it. This isn't something taught in colleges or even discussed much among developers themselves. Developers are supposed to pick it up as they go.
Here are two articles which has shaped my own thinking on the topic.
- This is article about how to read mathematics. Surprisingly, a lot of lessons apply to reading code also.
- This is more to the point of reading code. This article attracted a lot of attention sometime back.
Firstly, we need to be prepared psychologically:
- Don't hate the code: Everyone has their own style of writing code which might not match with yours. Also, a lot of production system have been through many hands and many requirement changes. Naturally, the code reflects some of that rough and tumble roller-coaster ride. Hence, respect it because it is something that currently works. Do not start thinking and cursing the developers about how it could all have been done better.
- Resist the temptation to rewrite code: While reading, you may encounter code which you know you could write in a much better way and improve it for everybody. Don't do it. Unless may be you have the original developer sitting next to you and there is a suite of unit tests to convince you that your changes will not break anything. Reading code is like surgery. Do not make it a re-engineering project.
Once you start reading the code:
- Take your time. Read it slowly. Don't read too fast. If you don't understand what you are reading, slow down, test that piece of code separately or for the moment, treat it as a black box, as a function whose body you will get to later.
- Keep notes: While reading the code, you have to understand two thing - how the data is stored and the algorithm that operates on that data. Draw pictures for both. Draw a table perhaps for the data and a flowchart for the algorithm. Use a notebook or whiteboard, but its essential to write it out instead of keeping it all in your head.
- Focus on the big picture: Reading and comprehending code requires getting into the thought process of the original developers, understand the bigger problem they were trying to solve and build the same picture in your head. You do not have to understand every line. Also, understanding every line does not guarantee that you understand the big picture. Once you have the big picture, you can use unit test or do a line by line walk-through using a debugger to understand a particularly tricky piece of code. However, the debugger should be used sparingly only as a secondary tool to further your understanding.