I recently finished reading How to Read a Book.
I didn’t read this book with programming in mind. However, while reading it I kept thinking that we could apply the same approach to reading and understanding a programming project.
I don’t mean to pick a codebase, print everything on paper (or even on PDF and use an e-reader) and read it before going to bed of course (really. Please preserve the environment and don’t print code on paper).
But like many books don’t deserve a thorough read, many others deserve to be read end to end, and even multiple times. The same goes with a codebase. Many of them will be worth reading in chunks over codebase over and over to fully grasp it, and to turn the “magic” into science. Not because it’s poorly written, but actually because it’s complex.
In this sense, reading a book is comparable to reading a codebase, and this it what I’m trying to convince you of in this post.
In How to Read a Book, the authors divide reading in 4 levels. Each of them encompasses the previous ones, and you can only reach a level if you have a firm understanding of all the ones before it.
1. Elementary Reading
Elementary reading, also known as “basic reading”, “rudimentary reading”, or “initial reading” is the reading most of us are taught in elementary school (or later in life in the case of second languages).
Applied to programming, being able to read “elementary” means reading the language’s syntax and understanding what it is going to do. There is no consideration of dependencies, possible optimizations or how methods interact with each other.
If you can understand an “hello world” in a language, you are basically able to do elementary reading.
2. Inspectional Reading
Inspectional reading consists in intelligently skimming through a book with a limited amount of time. Not the casual browsing through it though.
When performing an inspectional reading, we are going to try to understand not only what the book is about, but what its structure and its parts are. In essence, you are going to try to understand what the book says before reading it.
Applied to programming, it means we are going to look into how the codebase fits in its ecosystem. We are going to try to answer the following non-exhaustive list of questions:
- Who is using the codebase?
- What are its dependencies?
- What other projects depend on it?
- How can I compile it?
- How can I run the tests (does it have tests?)
Regarding understanding of a project’s codebase, this level of reading will also consist in reading the documentation, trying to install the project and running it.
Inspectional reading is the most common read we perform on a codebase. We will try to use the project, with no further understanding required. Doing it intentionnally will let you discover early if you’re looking at the wrong book/project, and avoid wasting time.
3. Analytical Reading
Analytical reading finally gets into the core of reading. To quote the authors,
Analytical reading is thorough reading, complete reading, or good reading
After doing full analytical reading, the book will become your own. You will make one with it.
Obviously, that takes a lot of time. The authors compare inspectional and analytical reading as the former being the most and complete reading that is possible given a limited time, and the later as the most and complete reading that is possible given unlimited time.
After doing a thorough analytical reading of a codebase, you should be a frequent committer. You should have a broad grasp of all the project’s intricacies and be considered an expert.
Full analytical reading can take years, especially since contrarily to books, most codebases evolve with time. So you need to keep up to date at the same time as you gain more knowledge.
The authors describe analytical reading as many, and organized questions of what you are reading. I like to take the same approach with a codebase. I will try to answer “how is this project handling X”, which often brings me quite far into the internals of that codebase. After a while of asking many questions, you end up getting a pretty good knowledge of the entire project.
4. Syntopical Reading
Syntopical reading is the most difficult, challenging and rewarding level of reading books.
You will be reading many books, and placing them in relation to one another. You will not only compare the texts however. With the help of the books you read, you will be able to construct an analysis of the subject which may not be in the books.
Syntopical reading, when applied to programming will consist in understanding how many projects are designed, regardless of their language and architecture in order to be able to better design another one.
It is in a way one’s entire career, as we get better at writing by reading other people’s. It can also be restricted to understanding a specific topic, such as “how do threads work”, or “how to write cloud-native apps”.
Syntopical reading isn’t the same as doing an analytical read of many books. Some books in a syntopical corpus will require a thorough read, while others won’t require more than an inspectional read.
Postface
I find this pragmatic approach to reading a book quite appealing (and demanding). And applying to understanding new codebases seems like quite a good way to get to a broad understanding of it.
If reading this article convinced you in any way, I would definitely recommend giving How to Read a Book a read (an analytical one).