How to Read Code
Some advice floating around the internet says learning to read code is one of the best things you can do to improve your code. So I took some time to explore the subject to get a feel for approaching code that I didn't write.
When I first started learning, I don't remember a single course or book that even discussed this; they all focused on writing programs from scratch. However, the reality is if your programming, at some point, you'll be spending A LOT of your time reading, fixing, or improving code that already exists, and yes, you may have even written it, but that was months ago. So if it's something we'll be doing anyway, we better spend some time getting good at it.
Why You Should Read Code
Let's explore three excellent reasons to read other peoples code.
Read code to learn how something works. For example, once while learning Node by building a command-line interface (CLI), I needed to handle arguments passed into the command line. The first argument was the command, and then any subsequent argument was an option for that command. While reading through the documentation and code examples, I could see that the arguments were all returned as an array. It's great because an array is a handy data structure, especially when the order of the arguments is essential.
On NPM, several packages help with handling arguments. We could, for example, take a look at the top three packages and look at their source code on GitHub and see how each one handles that argument array.
Reading how different people handle parsing arguments using arrays can open our minds to what's possible whenever we are looking for a way to handle arguments in our code.
Read to recycle and reuse. Now let's say we want to build an argument parser of our own but not for a CLI this time and not using Node. Let's say we've made a web app that takes arguments from an input field and, depending on the argument and options apply a simple animation to an SVG.
From what we've learned about handling arguments and options in our earlier research, we have a pretty good idea of what we need to do. However, rather than write it entirely from scratch, we could use some of the code we've read earlier to make a simple argument parser.
We're not using Node anymore, and none of the packages will work for this application, but they'll provide a great place to start since we already know how the code is supposed to work.
Read for the fun of it. Let's say we aren't looking to learn anything new; we don't need a specific bit of code to borrow implementation details from; we are just curious.
We see some project that has been trending on Twitter, and we are sitting at the Doctor's office with time to burn. So instead of playing a game, browsing social media, or whatever else we may be inclined to do, we can do a deep dive into the project's source code.
It may not be as engaging as that new trade paperback your reading before bed. Still, you'll probably learn something about how the code works and have a great source to come back to when you need to solve a similar problem. Plus, you may find it enjoyable to read and understand high-quality code.
How to Get Started
If you've tried to dive into source code before and have gotten immediately overwhelmed, you probably appreciate just how difficult it can be to get started. So let's see if we can make it a little more manageable with the basic rules.
Start Small
Don't just dive into the first extensive library or system you find. Start small. Starting small could mean using code examples you found on blogs or documentation. Small packages on NPM or other package repositories are an excellent place to look too.
The widely used open-source libraries and frameworks have a lot to offer but get your feet wet with the small-scale stuff, and you'll feel way less overwhelmed. Once your feeling more confident, heck ya, go for it.
Find High-quality Code?
While You don't always get to pick and choose the codebase you have to work on, I'd recommend that you be pretty selective about the code you choose to read. High-quality code will give you the best overall value for your time, but how can you tell the difference between high-quality code and low-quality code? The definition of high-quality is something that not everyone agrees on but let's start with a few straightforward rules that will allow you sus out the good stuff:
- A codebase that is well-maintained and popular will probably be a safe place to start.
- The code shouldn't be unnecessarily complicated, and the structure should make sense.
- There should be a consistent style throughout.
These rules are for getting you started. Feel free to add your own rules as your get more traction and confidence.
Make the Code Work
Once you've found some small high-quality code to work with, the next step is to open it up in your editor or IDE and make it work. Again, it's all about understanding how the code is designed to work and getting immediate feedback on what's happening, and exploring why it's happening.
Change the Code
Finally, it's time to change the code. Changing the code will let you test your understanding but remember to start small, and as your knowledge improves, gradually increase the scope of your changes.
Here are some ways to change the code:
- Write tests. There may already be tests. If there are tests run, read them and run them. If there aren't any, write some.
- Add a feature. Give the code some additional functionality.
- Fix a bug. Did you find a bug in the code? Maybe an edge case that the original author didn't consider?
- Refactor the code. Maybe there is a specific design pattern that would be a better fit than the current code.
What to Do Next
As you get better at reading, understanding, and modifying source code, now would be a great time to dive into open source projects and look for ways to contribute. In addition, reading other people's source code will provide more opportunities to practice and let you work with others.
Here is a great article on contributing to open source from Kent C. Dodds when your ready for that.
Kent C. Dodds