Become a better programmer: How to read source code

There are many benefits to reading source code. You will discover new constructs and libraries, resonate with other code maintainers, but most importantly, learn how to organize the code so that it does not become unmaintainable due to extreme internal complexity.

But there is a downside, which is that reading source code is too difficult. Every time I see a new code base, this dizzy feeling fills my mind. My heart tells me that I don't want to wade into this muddy water at all.

This is a (hopefully) normal reaction. When our brains are exposed to too much novelty, they reject it. The powerful pattern-matching machine that the Creator has given us simply cannot find a pattern. All the abstractions are new to us, and the class names are completely unfamiliar. Where does the program even begin to execute?

The general advice I can give is as follows: 1. Find and build an initial foundation that you understand, usually the main entry point. 2. From this foundation, gradually explore the main features. 3. Record what you find.

Start from scratch

The trick is to give yourself a starting point. Here's what I do. I run the program with the -h option and call the help command. Then I copy one of the help docstrings and use it as a search term to search through the codebase to find the help doc. Usually, calling the help command will put you pretty close to the main entry point of the program.

Identify the outline

Once I found the main entry point, I ran a few of the examples provided in the documentation. Then, I tried to trace the main code blocks and get a rough idea of ​​how everything is connected.

I ask myself, is there a manager that calls a bunch of helper functions and classes? Are there peers that take turns passing control? Is there a main queue of tasks that the program executes step by step?

Knowing the big picture helps you understand the small details. If you read on without understanding the main flow of the program, you'll likely be overwhelmed by the details.

Take notes

I tend to take notes directly in the code. When I do, I use special comment characters (for example, #=> instead of the usual #) to distinguish my own notes from the original author's comments.

If you come across a clever trick, a confusing flow, a beautiful use of a programming construct, or anything else you want to remember, be sure to take notes. If you get stuck, you can also make a note to remind yourself to go back and read the part you didn't understand later.

By writing down your thoughts, you are actually making that piece of code your own. Over time, you will begin to naturally use those newly mastered constructs in your work.

Integration

Learning programming is a continuous process of reading and writing code repeatedly. As long as you are willing to be exposed to different styles and codes, you will eventually form your own unique perspective and thinking.