A guest post by Stephen Malina, my partner in crime on Mu.
Most programmers agree that we don't read enough code. The interviews in Peter Seibel's book, “Coders at work” highlight a comical contradiction: almost all the programmers interviewed by Seibel recommend that others read code for fun, but none of them routinely do so themselves. Seibel even asked Hal Abelson (of SICP fame) directly about this phenomenon:
Seibel, James Hague and others have all tried to justify why code reading is so uncommon, and they make good points. But perhaps the conversation is led astray by use of the word ‘read’. I wonder if Abelson and the others would have had more examples if Seibel had asked them what code they had learned about for fun. Perhaps the word ‘read’ put them in a passive frame of mind, causing them to filter out programs they'd hacked on?
We all read code already; it’s just that we usually read when we want to edit. And the comprehension that questions about reading are really concerned with—it comes from both reading and writing, interleaved in complex ways.
That hacking produces better comprehension than passive, linear reading fits with what we know about learning. Barbara Oakley, Herbert Simon, Cal Newport, and Anders Ericsson all describe how solid understanding emerges from active exploration, critical examination, repetition, and synthesis. Hacking beats passive reading on three out of four of these criteria:
- Active exploration: When you hack, you want to eventually produce a change in the codebase. This desire guides your path through the code. When you read passively you let the code’s linear flow guide you.
- Critical examination: When you hack, you evaluate existing code in light of the change you want to make. Deciding what to use and remove keeps you from accepting the existing system as canon. When you read linearly, you lack a goal against which you can critically examine the existing code.
- Synthesis: To change the program as you desire, you synthesize existing code with new code.
- Repetition: Neither hacking nor linear reading involve useful repetition, unless you treat your change to make like a kata and mindfully re-implement it multiple times.
Learning through hacking also leverages the natural structure of a codebase. Good books guide their readers through series of questions and their answers, but codebases are inherently non-linear, like a map. You can ask an infinite number of questions of a map. How far is it from A to B? Which is the nearest town to C? But you can’t expect a map to tell you what questions to ask, and it makes no sense to read a map linearly from top to bottom, left to right.
Reframing reading as ‘navigation’ suggests that our conventional discussions of clean code and interfaces ignore the things that actually make unfamiliar code accessible to outsiders. Clean, solidified abstractions are like well-marked, easy-to-follow paths through a forest — very useful if they lead in the direction we need to go, but less useful when we want to blaze arbitrary new paths through the forest.
Instead, let's focus on guiding exploration, making it easier for readers to answer their own questions about codebases. I’m still figuring out how to do this; so far I have just a couple of preliminary ideas:
- Suggest features in your code that make good exercises for re-implementation.
Provide an initial Git commit without the feature, give them hints where
necessary, and link them to the actual change plus others’ attempts at
producing it.
- Rather than conceiving of documentation as something that explains
individual modules, focus on overviews of how the modules fit together (like
Fabien Sanglard's
for Git).
Afterword
Others have explored similar ideas from different perspectives:
- “How To Be A Hacker”: Eric Raymond discusses what he calls the “the incremental-hacking cycle”, a process by which someone gradually expands their understanding of a codebase by making bigger and bigger changes to it.
- “How to read a math textbook”: David Maciver describes a problem- and theorem-driven approach for learning math which you could adapt to reading programs.
- “The Benjamin Franklin method of reading programming books”: James Koppel's take on Anders Ericsson.
comments
Comments gratefully appreciated. Please send them to me by any method of your choice and I'll include them here.
a) Conventional approaches to making codebases readable are like still lifes or depictions of a single scene. But since codebases are non-linear, what they need is something more like a mural. Something that can be read in many different ways. Like a Thangka, or a codex:
(source)
Something with multiple "centers" of narrative, to use Dave West's terminology.
b) We typically focus on the ability to find the right information. Your post is pointing out that knowing what to ignore is under-emphasized, and the desire to modify provides a powerful "ignore this" heuristic.
c) There's the old story about how paving cowpaths is often a better way to decide where footpaths should go. (The best source I could find is the second occurrence of 'footpath' in this post) In these terms, perhaps we programmers are prematurely paving narratives in our codebase. In the terms of James C Scott, programmers are being Authoritarian High Modernist in assuming that they understand all the ways future readers may try to read their code. Some humility for the inherent illegibility of the activity of programming (particularly how other people read code) may be in order.
d) There's a body of work on how the human brain comprehends messes. If you see your codebase as a mess, that results in some set of ideas for improvements. But the jungle metaphor results in a whole other set of ideas.
e) When we programmers read code, it is purposefully but non-linearly. Like Bruce Willis in "Die Hard": barging through walls, moving through elevator shafts and air-conditioning ducts. However, when we write code, we assume an idealized reader who will read our creation aimlessly but in order, content to follow our lead in all regards. This is a pretty big disconnect in all our minds.
f) Often you have something useful to tell the reader, but no obvious place to put it that the reader is likely to see at the right time. Perhaps making code easier to explore is just a matter of creating Schelling points.
What would be even better is if this live system map is hyperlinked to the static source files, so I can click on an object and jump to the source class definition, for instance.
I really appreciate repositories with clear instructions for how to build as well as perspective on the key run time decisions and complications so that I can troubleshoot effectively.
That's it! A big reason for this is minimizing dependencies. Every library a tool needs, every compiler that it requires a specific version of, is a place where somebody will trip up and have a bad experience.
That said, I believe that the resistance to code-reading as a common method is derived from an unwillingness to look things up. Too many times we read code without actually knowing whats happening behind the words and symbols - and this, I feel, is where the "Great IDE Debate" comes into play. You can read all you like - but if you can't build it, or can't get hints or even executables from the environment you're using to do the reading, then that is definitely a hindrance. But yet, IDE's like to hide a lot of details about whats really happening under the hood, and so having a comprehension of the build process is also key. Code-reading is not enough: Code-building is also significant.
So a big part of developing code-reading skills is in refining a) ones ability to use the IDE as a tool to navigate and build, and b) not depending too much on skill-a), also.
Hassan