There are two ways we as developers interact with code: the first is in writing code, and the second is in reading code.
As the writer of code, a natural tendency is to minimize the amount of time you spend writing it. If the code works, and tests pass there is a strong sense that it should be committed and the next task started. You'll be a hero for getting it done quickly, right?
Let's not forget the other option: refactor your code for greater readability.
Consider what might happen when you've completed your code.
At my job, pull requests need two OK’d reviews to pass. If the reviewed code doesn't pass, the author will have to re-read it as they rework it. And there is a good possibility that the next person who works on that code won't be the original author or reviewers. We've written once or twice and read 3 to 6 times.
If the writer of the code favoured their interest in completing the task efficiently, then it may have come at the cost of readability. If the codebase has any longevity, then the number of times code is read quickly dwarfs the number of times it's written.
Hopefully we agree that many more people will be reading the code than writing. But how painful could it be to read the code? You're a good developer who writes readable code. Right?
In terms of readability, your code is always worse than you think it is. This is because you had a magical superpower while writing it, that no-one else will have when reading that code.
The superpower is context.
As the writer of the code, you were privy to the thought process that was occurring as this code evolved. The reader was not. As you jumped between controllers, views, tests, fixtures, models and made changes, broke things, fixed things, you built up a story in your head of how the new code interacts with the system. As you jumped between coding and clarifying requirements with the design team, and the QA team, you continued to add to this mental model and amend the code accordingly.
The reader of the code didn't have this experience. They just see an assortment of code that wasn't there before.
Imagine your autobiography written as arbitrary unordered facts: "Favourite food at age 7, still the same as last year. In January of 2005 I changed back to my original major. That thing Steve did was so hilarious. LOL. …”
To you it might make sense. To anyone else, it's painfully unreadable.
It's not enough for a biography to contain the right facts, it needs to tell a story. It's not enough for code to work, it needs to tell a story.
Therefore, my recommendation for writers of code is to take the time, after the code works, to organize the code as if it's purpose was to be read.
My recommendation to reviewers of code, is, if a pull request is very hard to understand, the review should probably be "this is very hard to understand". Request changes, and don't waste too much time with the review. Don't be a hero and struggle to understand it. Definitely don't pass it if you don't understand it. After all, a reviewer might be the next person to work on that code, and they need to be clear on how it works.
If you've read this far, you might be wondering how to ensure your code tells a story.
I'll get to that in my next post.