Reading code is a different experience to writing code
When writing code, the first thing I focus on is making it do the thing I want it to do. After that is achieved, I might end up with a large file or method. Once I reach the point where I know what the code is doing, I kind of wish it would get out of the way.
Enter: abstraction. If I could take out all these lines of code and abstract them into neat little functions, I could make the main method read like a book!
The CodePen Rails codebase went through an era of organising code this way, so we have many methods that look like this.
def new @new_user = User.new @init_data['__pageType'] = 'signup' set_owner set_pay_ownable_tier set_current_interval @team_user_pending_invite = find_team_user_pending_invite store_request_session_return_to respond_to do |format| format.html do render(layout: 'signup-and-login') end end end
When you’re the person authoring this sort of code, it is satisfying to look at. Look how neat this is; all the implementation details are tucked away in places that are not right here. I don’t need to see those details because I’m confident they are doing what they should. I wrote it.
When you’re the person reading this code three months, nine months, or three years down the track, you can’t be confident that everything is doing what it should. You can’t be sure that the function names tell you everything you need to know about this code. You have to jump to their definition and see what’s inside them.
And when you’re in a codebase that has been abstracted to high-heaven, having to “Go To Definition” up to six times before you arrive at the actual logic in a program is maddening.
We’ve been moving our CodePen backend from Rails to Go. When I first started using Go, I found it to be “disgustingly verbose”. It seemed the “Go way” to write code was to err on the side of leaving logic “in-line” rather than abstract it to another location. “A little copying is better than a little dependency.”
However, when I returned to reading the old Rails code, I found myself missing the simplicity and verbosity of the Go code. When I switched from code writer to code reader, clever abstractions were far less appealing, no matter how well they were named.
As my experience as a developer grows, I realise that if my goal is to write clear code, I should put myself in the perspective of the person who has to come back and read the code later, whether that is a team member or myself in 6 months.
Thanks for reading! If you'd like to share your thoughts you can leave a comment, send me an email, Tweet at me, or add an issue on GitHub.
The Comments system is powered by a third party service - Talkyard. Sometimes they don't load 😞. If you're having trouble leaving a comment you can send me an email.