Optimizing for understanding

· br11k's blog

When code review is the biggest bottleneck, you need to optimize for understanding.

Optimizing for understanding #

foxes

So now we have a problem. I get the feeling that you are enjoying this way too much. And you haven’t even hit the chapter where I use jump-roping songs to help you learn how to parse XML!

If you’re already enjoying this, then things are really going bad. Two chapters from now you’ll be writing your own Ruby programs. In fact, it’s right about there that I’ll have you start writing your own role-playing game, your own file-sharing network (a la BitTorrent), as well as a program that will pull genuine random numbers from the Internet.

And you know (you’ve got to know!) that this is going to turn into an obsession. First, you’ll completely forget to take the dog out. It’ll be standing by the screen door, darting its head about, as your eyes devour the code, as your fingers slip messages to the computer.

Thanks to your neglect, things will start to break. Your mounds of printed sheets of code will cover up your air vents. Your furnace will choke. The trash will pile-up: take-out boxes you hurriedly ordered in, junk mail you couldn’t care to dispose of. Your own uncleanliness will pollute the air. Moss will infest the rafters, the water will clog, animals will let themselves in, trees will come up through the foundations.

But your computer will be well-cared for. And you, Smotchkkiss, will have nourished it with your knowledge. In the eons you will have spent with your machine, you will have become part-CPU. And it will have become part-flesh. Your arms will flow directly into its ports. Your eyes will accept the video directly from DVI-24 pin. Your lungs will sit just above the processor, cooling it.

And just as the room is ready to force itself shut upon you, just as all the overgrowth swallows you and your machine, you will finish your script. You and the machine together will run this latest Ruby script, the product of your obsession. And the script will fire up chainsaws to trim the trees, hearths to warm and regulate the house. Builder nanites will rush from your script, reconstructing your quarters, retiling, renovating, chroming, polishing, disinfecting. Mighty androids will force your crumbling house into firm, rigid architecture. Great pillars will rise, statues chiseled. You will have dominion over this palatial estate and over the encompassing mountains and islands of your stronghold.

Why’s (Poignant) Guide to Ruby, chapter 3

This is how I got into Ruby, 12 years ago.

I also kind of wanted to thank everyone who made an effort to make this language and ecosystem around it truly special, no specific order: Matz, DHH, bbatsov, tenderlove, Sandi Metz, 37signals, _why, pragdave, and of course mpapis who I still remember my system design interview with (we were trying to design a search bar during my application to Toptal, and I utterly failed — that was April 17th, 2018).

To me this language will always be the most important, because it prioritizes understanding code over anything else. And I would love to see more tooling written in Ruby. You can make your own DSL and easily write a thorough spec that maps to your domain.

When designing code, I am thinking in RSpec. Sometimes in plain Ruby 🙂And I think this is as important as it could be today. And my most important realization is about just one thing.

How can we optimize for understanding?

I've been thinking for a very long time about this. Even before LLM explosion (2015-2020), I've always been stuck digging through git commit history to reverse-engineer specs from poorly written code, so I could understand what exactly needs to happen to fix the problem.

And so to me the answer to that was simply writing proper commit messages: context and why, not what. And RailsConf 2015 talk is a very good "confirmation bias" video that still holds today🙂

However, there was another problem I learned about from Joel Spolsky blog: Writing Functional Specifications. This stuck with me for rest of my career, since after I discovered it (around 2014 or so). And here's my poor-man biased observation just from my 12 years of bashing my head against problems.

Writing a proper product/technical spec is either misunderstood, difficult, or not budgeted properly.

I believe I can say "I've seen it all". But feel free to correct me and I'll be happy to discover if there are teams writing (and maintaining) product specs today, on a scale!

Last 2 years my mind have been wandering about what exactly is the gap between "we have no specs" and "I edit any file in a repository and I know which feature is going to break". And to me the idea is very simple.

SCIP indexes.

Yes. Your LSF. Your code — this is all graphs. A file imports symbols and exports them. And product spec is yet another entity. A graph node. With properties and links to code. And I feel crazy that I'm seemingly the only one who bridges these two concepts now. I tried searching for any solution and I couldn't find any. There are only building blocks (e.g. indexers) but no tooling exists that connect these two concepts and tries to standardize it.

And turns out, you can map a lot of reality onto graphs. And Math is yet another tool to help you bridge how the World operates and how exactly your code needs to run. But I don't want to dive into TLA+ right now, although to me it seems that next generation of programmers would have to become mathematicians 🤷

Because you can describe everything with Math... well, except Black holes, but I'm pretty sure we'll figure that out soon 😀

So long story short, these are two articles I wrote hastily (just couple days between job searches) is a tip of the iceberg of what I think needs to happen.

Solving the Code Review Bottleneck #

My idea is that we can solve these problems, one by one, with deterministic approach. And by deterministic I mean a command line tool. A Rust crate. Or a Ruby CLI script. Doesn't matter how exactly. But documenting your work properly can be an algorithm. I tried to detail it as much as I could in the article. And I wrote this note back in 2023, long before people realized the bottleneck.

Honestly, I can't even find a proper word how I feel about this. I wish I was just plain wrong, but no, it seems my intuition all these years have been right. Again, I'm happy if anyone could point me out anything incorrect, I'm actively seeking to prove myself wrong, as everyone should be (thanks Jeff!).

You might still have question

"but what is the point starting the article with Ruby reference?"

And yes, I'd propose writing critical specs in the language that is optimized for understanding. Eventually we'd have to shift to Math (and I'm dying just thinking about it) but right now we need something that still makes sense to an average software developer, and not major in Calculus.

tl;dr #

I am trying to solve the "code review bottleneck" many people realizing just now, and I've been fighting for it since like 2020, teaching other developers to document properly their work. Even before LLMs were able to do tab completion. And today I'm cooking a possible solution to save us all. This can/should be automated.

I'm optimizing for understanding and I need as much help as possible. Here's my contacts if you need me. If you wanna support me financially, I can maybe setup something later (e.g. Github Sponsors / Open Collective / Ko-Fi), and thank you if you feel this is important enough to consider doing so.

last updated: