How complicated is it to read your own code after taking a break?
I decided to return to a project that I hadn’t touched in a month because I wanted to add new features. To my surprise, it took me a whole day to understand what I had written before. When I started reviewing the code, I had to remember how the structure of the react component worked and how they were connected to the back end.
This issue made me reflect on the fact that I couldn’t read or understand my own code, which I had written just a few weeks ago.
- What does this mean ?
- Why wasn’t I able understand code if I wrote it just a month ago ?
There’s a principle in programming that says:
Reading code is harder than writing it.
When I was at Flatiron School, I would be working on my projects and ask professors simple questions like:
- Why doesn’t this code work ?
- If I’m mapping through an array why does it throw an error ?
Sometimes they would have an answer because they’d seen the error before like “Cannot read property of undefined.”
Other times they would stop and say:
“I don’t know enough about the code that you’re writing to understand how it works, walk me through it and maybe we can figure it out together.”
As a student it was easy to explain code that I was writing at that moment, but what would happen if a month later, someone asked me to walk them through my code. How can I walk somebody through code that I can’t read?
I faced that question a few days ago when I went back to add features to my code (like I mentioned in the beginning). I was having to walk myself through my own code and I wasn’t able to read it. So, I came up with a system that would help me the next time I need to revisit code that I previously wrote.
- Document Everything.
I had created wireframes for this project but key changes that were made later were not reflected. I had a visual description of what I wanted the project to look like but nothing written so I had to rely on my memory. I could have saved time by documenting every change that I made on the project and being diligent about updating my wireframes.
2. Components hierarchy.
It was very complicated to see what was happening on my React JS front end. It took time to re-understand the structure of the components, even though I had the wireframe. It would have been easier if I had a text file with details explaining the hierarchy.
It is well known that commits are super important. When I was checking my previous commits, I realized that I wrote too much code before commiting. So I started committing sooner and more often with better messages, making it easier for me to revisit code.
Another change I made was to write comments on all of my components where there was something important to mention. The truth is that this makes everything way easier.
5. Naming Convention.
Just name everything after what it is or what it does, it’s so much easier to follow.
This is the most common developer mistake and one of the things that causes us to lose a lot of time.
Everybody writes code in a different way. In the past, I would write code that worked first and then revisit it to refactor. The problem was that there were so many things that I would leave behind on projects thinking, “I’ll come back to it later” and then I didn’t. I also wouldn’t document or write comments where I knew I could easily refactor the code making it more difficult than it should be to revisit. Again, documentation is a very important step because if you do prefer to go back and add features or fix problems then this will make it so much easier.
Since following this procedure, I can say that going back to my old projects has become much easier. Of course I had to revisit all of them and retroactively follow the steps, but now when I make a new project, I follow these six steps and will reap the benefits as a result.
It is important to mention that this was my way of improving my own projects and after showing it to two of my colleagues, they were impressed by how easy it was to follow my code.
Although not all the code out there is written for you to understand it, if we follow good practices maybe at some point everything will be easier.
Thanks for reading!