How to read code — better
I believe that for a programmer, the amount of time spent Reading code versus the amount of time spent Writing code follows the Pareto Principle
A research done on Measuring Program Comprehension conveys that, a programmer spends anywhere between 50–60% of time on code comprehension and 20–30% of time in code navigation.
Irrespective of the numbers, I think anyone who has spent more than a year working as a software developer would agree that we definitely spend most of our time reading the code than writing it. But the significance of reading code is often neglected. And I think we should consciously spend some time and effort in improving this skill.
Below are some suggestions on becoming better at reading code:
1. Read Good Code
I can hear the slow-claps. But honestly, I think reading good code is the first step towards getting better at reading any code.
Good code is something that feels like poetry. When you read such code, you develop interest in reading code, and furthermore, it encourages you to write better code.
You can find the inspiration from this reddit thread for some good open source repositories to browse through. (Flask is one of my favorites)
2. Stick to an Editor and become a Pro at it
I believe that getting accustomed to a feature rich text editor (like VS Code or Sublime Text) is arguably better than getting stuck to a language specific IDE such as (PyCharm or PHPStorm — IntelliJ is an exception though!).
As we saw at the beginning of the article, around 20–30% of the time is spent in navigating the code, so the ability to navigate faster with a text editor that you are well versed with (and mastered the shortcuts), will speed up your ability to hop around the code base quickly and grasp the functionality.
I agree that some IDEs offer better navigation with respect to specific language you’re working with, but you can achieve almost the same functionality with a hackable text editor — with a one-time investment of time and effort in setting up things (shortcuts, extensions and so on).
Being language agnostic is a desired skill for a developer these days and in my opinion, being attached to an IDE is not recommended for the long run.
3. Refactor other people’s code
When you come across a piece of code that you don’t understand, try refactoring it. Only then you would understand the importance of that piece of code that seems like it doesn’t belong there in a first glance.
I have come a full circle in this respect where I removed an old piece of code assuming that it has no business being there, only to introduce a bug, which was found out couple of days later, forcing me to diligently put back the code I removed — but this time understanding the better of it.
4. git blame
git blame is my most favorite feature of git. Apart from using it to look up the name of the developer, who wrote the cryptic verses amidst of poetry to curse the poor guy (only to find out that it’s you who wrote it 6 months back) git blame can be used effectively to find out why that piece of code/functionality has been added.
Assuming the repository contributors follow some guidelines on naming commits, writing good PR descriptions and linking to right issues, you can explore the whole story behind a single line of code.
5. Read Test Cases
If you are lucky enough to be working on a project or a code base that has good test coverage, it is highly recommended to go through the Test Suite to understand the code.
Good test cases enforces the code to just be what it is supposed to be. Hence test cases serve as a good tool in understanding the purpose of code.
As Uncle Bob states,
Tests are a good documentation of what a piece of code is supposed to do.
6. Connecting the dots
And finally, connecting the individual pieces that you understand is a good approach for improving the understanding of the code base. When I begin to understand a piece of code or functionality, I try to back track my way towards the root.
Starting from a single point and branching out from there is a good strategy in improving the code comprehension. After a few walks back and forth this path, you will start getting familiar with the What’s and the Why’s of the code.
Epilogue
All in all, reading code >> writing code (I guess I repeated this enough times in this article).
But what about writing good code, which makes the experience of reading better? Well that deserves another article!
I am Srinidhi Bhat and I thank you for spending your time on reading this article. A few claps on this article would go a long way in encouraging me to write more.
Any comments, feedback or criticism is most welcome!
Note: This article is heavily inspired from Clean Code principles of Uncle Bob and countless articles I read on the Internet.
Some references:
[1] Clean Code Playlist
[2] Developers spend most of their time figuring the system out
[3] Measuring Program Comprehension: A Large-Scale Field Study with Professionals
