Monthly Archives: August 2009

On reading code efficiently

As someone who learned to program the non-traditional way (ie: by reading and hacking on already written code) rather than ground up (ie: by writing hello world and progressing from there on), I feel the ability to read code is often under-stated when people offer advice on good programming practices. Especially considering that any good programmer, in her entire programming career would end up reading more lines of code than writing !

I have thought a bit about this subject (and also observed good programmers read code). While there are many tools which can be used to efficiently read code, I’d like to share my thoughts on the methodology.

Good programmers read code the same way most of us read a newspaper

  • They’ll look at the main entry and exit bits (the headlines) to get a ‘feel’ or overview of the nature of the application. This might also involve reading any design docs or UML diagrams or even badly drawn out bunch of boxes. The better that people are at looking and understanding the big picture, the less they have to look at to get it.
  • After that, they might jump into the bits that interest them (in our analogy — the sports section, the comics or *shudder* page 3). So, coders interested in just using the API will start exploring the headers. Those interested in hacking on the code, will start looking at the source files that are possibly named according their area of interest (that’s why naming and source file layout also is important while writing code). This is where cross-referencing tools help.
  • When looking at the code itself, for example, when tracing through a function, some bits are more or less taken at face value (as we do with phrases like ‘from reliable sources’ or ‘an independent study’) …at least during the first reading. In other words, faced with a statement like this:
    devices = probe_for_devices(args)
    …good programmers would only dive-into the definition of probe_for_devices() after they have a general enough understanding of why doing that is necessary in the caller (unless of course, /that/ function was what they were interested in looking at all along)
  • Now, when the time comes to not just passively reading but /interacting/ with the code, good programmers would first look for tell-tales signs on making such interactions easy (ie: what kind of logging/debugging facilities does the code provide ? can sub-components be built and tested independently ? Are there any compile time options available to assist this effort ? Can we get an intern to figure all this stuff out[1] …etc)

Doing all of the above of course is fun only if (again like natural written language), the quality of the code you are reading is good. Bad written code is also badly read code.

Now all that said, knowing how to use your tools well (ie: your editor, code cross-referencing tool, the man pages, API docs ..etc) improves the efficiency with which you read /immensely/. That’s how good programmers are able to ‘walk’ through the source in the same manner as the system would during execution.

FWIW: My tools of choice are, vim, cscope and a decently fast internet connection

Thanks for reading. Your views and comments are welcome.

[1] That’s where I usually came in šŸ™‚