Understanding Code You Didn’t Write

I’ve been thinking recently about skills I wish were taught better in computer science curricula. (Previously I discussed the ability to write.)

Here’s another skill that we often need: The ability to quickly understand code you didn’t write.

As open source is used more and more, we increasingly ask engineers to drop into a large codebase that neither they nor anyone on our team is familiar with. Typically these source trees do not have separate design documentation, and also it’s normally not possible to have the original designer give you an informal white-board talk about how the code is organized or why it was designed the way it is.

The ability to quickly wrap your head around this code, and then begin modifying it, is a great skill to have.

Maybe there is a bug that needs to be fixed, or maybe we want to extend the code to address some new problem. To be clear, we don’t want the changes just hacked in; we’d like them to be made elegantly, along the lines of the original design, and following the style of the remainder of the code. Ideally, these modifications would be so seamlessly integrated that the upstream maintainer of the code will readily accept them.

I’ve observed some engineers are much better at this skill than others, and the ones who have it are very valuable. Unfortunately, I don’t know how to teach it — although there are some interesting comments in this “Ask Slashdot” article. Like with many things, I suspect it’s a case where the experience of having delved deeply into someone else’s codebase makes you better at doing it the next time around.