How to Read Code - Developer's Secret Tool
Tags: productivity, beginners, programming
Published: 2020-02-28 17:34:17

I want to share a powerful tool I discovered some years into my programming career - code reading! Reading code just for the sake of understanding is a super useful way to spend an hour or two each week. 

Reading the source code for your main project at work is a great place to start. Real code, live in production. Other than improving your general comfort/confidence with a new codebase, here are some specific benefits:

- Code is the **truth**. If you see a function and it's written a certain way, that's how it works. Documentation can lie, other developer's memories can fail. What you see is how it works :) 
- If you've been reading code you'll have a better sense of the overall structure. The act of programming always requires figuring out two thing 1. what lines of code to write 2. *where* to put this code snippet you carefully crafted. The 2nd one is often more challenging.    


Before I share practical tips for how to read code. Here is something *not* to do. Do not try to understand the entire codebase. That is likely not possible and neither is it necessary for you to be effective. (When I started my 2nd job working on something I was really excited about, I decided that the thing to do is understand the entire source code of this whole project. I am going to know how everything works and how everything fits together and it's going to be awesome. Hm...it did not work out that way.) 

The process:

Choose a functionality you want to unravel. Pick your best guess at a starting point, follow methods, cmd+f is your friend here. If you run into an unfamiliar syntax or idiom look it up, make a note, keep going! 


Some practical tips:

- Acquire enough domain knowledge to understand design choices (but you don't need to understand how the entire healthcare industry works to work on a pill reminder software, for example)
- Use `git blame` (or similar in your version control system) to get a sense of two things - when was the change made and who made the change (useful for below tip)
- After you've spend some time with an area of the code, set up a info session with the developer that is most knowledge about that area of the code (they could be the author of the code or not). Have good questions ready, ask out of curiosity. After all programming is about people, right :) You may learn historical decisions and how this code has evolved.


Even once I realized reading code was a valuable thing to do, I had a lot of hesitation and I procrastinated on creating a code reading habit. Somehow, when you're new to a codebase, it feels overwhelming (for new and experienced developers alike!). But if you think about code reading, there is no danger here! There is no harm that can befall you, physical or psychological, by just reading letters on a screen and hitting cmd+f from time to time. It will take some time and initially it may all feel like gibberish. But soon enough things will take shape. It's like unboxing a 1000 piece jigsaw puzzle. 


I am curious to know if other developers read code just for fun? How do you approach getting to know a new codebase?

I imagine there are interesting things to learn by reading open source code. I haven't done much of that except for tactical reason.
That does feel less approachable. I have an idea! Perhaps it would help to have some starting points documented. (for example, start in this file#method if you want to learn about how we handle authentication). Maybe I will do that for the dev codebase. To be continued!

In the meantime, find a way to read code every week for fun. And it *will* become fun, I promise!