My Approach to Reading (Ruby) Code

As part of my journey to becoming a dev, I've been working through The Odin Project (TOP). One piece of advice that stuck with me through the lessons is to, after a project, spend some time reading code that's been submitted by other people on the same project. I won't lie, it's NEVER something I find fun to start.¹ It can also get overwhelming or frustrating or even just...boring. BUT, I've found that I learn quite a bit when I keep at it.

I've done it enough times now that I can say I've learned a few things about how to go about reading someone else's code. It isn't always straightforward. I mean, sometimes, the person's project is structured somewhat poorly (at least, based on the conventions I've been taught throughout the Ruby course on TOP). Sometimes, the code itself is messy. Whatever the case, this approach of mine has proven to be a good start.

My old approach: start wherever

My initial approach was to open a file, any file, in the repo of a fellow "Odinite"² and just...dive in.

I noticed that this almost always ended in procrastination, frustration, fruitless confusion, and burnout. Eventually, it just occurred to me to read code the way I intended for mine to be read: from main.rb (the part of my code with the highest level of abstraction) downward.

My new approach: top to bottom

My approach is rather straightforward:

1. Start from the main file (conventionally, main.rb) and read it through to the end. If the author has written their code well, this should help you understand what the program is doing and give you some surface-level insight into how it works.

2. The next thing is to tackle the methods one by one. You can do this in one of two ways:

   • file-by-file: after the main file, you sequentially read through all files in the repo. Conventionally, the project's core logic should be in a /lib directory, so that's where I go next.
   • call-by-call: you recursively read each method definition when you get to their invocation. This is after the initial reading still, and you always begin with the methods as they are called (line after line) in main.

   To be honest, this can get cumbersome (especially if you're reading my code cos I define a LOT of methods), so if that's the case, I'd recommend doing this only for the ones you find to be really vague or really interesting.

3. When you read a method's definition, re-read the place where it's called (or
   invoked). The point of this is to build a mental map of how the different parts of the code are [inter-]connected. This might also make it easier for you to mentally track return values, side effects and whatnot.

4. When you're done with all that, either give main a final read to look upon it with fresh eyes and deepened understanding or move on. Anyhow, at this point, I think you've done well.

When the person's code is written by AI

Every once in a while, I see a repo where I'm almost certain the code was written by AI, but that's okay still.

Reasons it's okay

That sort of code is always way more advanced and robust than mine, so it's a chance for a lot of learning (even though it's far beyond what the project's specifications were).

Furthermore, it's a sort of early practice for the kind of work I'll find myself doing when I move on to working with AI and when I land a job. Who knows? Anyhow, like Conquest said, "I take...the good with the bad". Sometimes, I skip it (when I just don't feel like it). Other times, I give it a read. Balance...sort of.

The problems I encounter here, though, include the following:

• Because it's written by AI, there are parts of the code that are more advanced than what I've been exposed to at the time, and that tends to get stressful very quickly.

• The people that submit code written by AI don't organise the code properly so it's all just in one file and that's just messy.

All in all, just be mindful of it.

Conclusion

Reading code is always kind of a hassle to start. But, I swear, sometimes, it actually gets fun to see other people's approaches and their innovations. This is your reminder to give it a chance and give it time. It kinda gets easier. Or at least, you'll get better at it.

Footnotes

¹ Cos you want to get to the next lesson or project ASAP and it's just so tasking to finish working on a project and then go looking at even more code you won't understand at first glance. 🙄

² Group name for people undergoing The Odin Project.