The Golden Middle Path - a blog by Amit K Mathur

How to read code

Programmers work and think in a language of their own. Just like any other language, writing and reading in a programming language are two different aspects and each 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. There are 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 mostly by accident and developers are expected to just do it. This isn’t something taught in class rooms or even discussed among developers very much. You are supposed to pick it up as you go.

Here are two articles which has shaped my own thinking on the topic.

  • How to Read Mathematics. This is article about how to read mathematical texts and proofs. Surprisingly, a lot of lessons apply to reading code also.

Here are the guidelines I have found to be useful. Firstly, we need to be in a right mindset:

  • 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. However, respect it because it is something that currently works. Do not start cursing the project and 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. If you are overwhelmed, take a break and come back to it.. 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 i.e. as a function whose body you will get to later.
  • Keep notes: While reading the code, you have to understand two things – how the data is stored and the general outline of the algorithm. Draw pictures for both. Perhaps, you can draw a table for the data and a flowchart for the algorithm. Use a notebook or a 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 to 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 tests or 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 fill in gaps in the big picture.

Once you have the big picture written out on a paper or a whiteboard, its much easier to start thinking about how you want to implement your changes and which all pieces you will need to test eventually.


Post a comment

(Formatting help)