Some thoughts about readability

A few weeks ago I started getting into Rust.

I thought some features were nice – traits are a nice generalization of the familiar templates. Ownership semantics was tricky, but I learned to reshape my neural connections to cope with it. I don’t know many things about Rust, but I can read most code. It wasn’t perfect in many places, but it seemed good enough to do its job well, and well enough for me not to hate it, like most new technologies that I try and run into million bugs.

And then it hit me like a train.

I decided to check out how one of the libraries I was using was implemented. Mainly to get a grasp of how its supposed to be used, and how to use it better. I mean, I was decently confident in my ability to read Rust, I thought I understood the basic concepts and that I could just follow the chain of implementation to understand what is going on.

I couldn’t.

The code was littered with macros and abstractions. The functions seemed like they did nothing. Nothing in the implementation was documented. What am I even getting from this library? Why does this function require my input type to implement Clone trait? I have no idea.

Try this: pick a library. Ask a question about it. Read the source to find out the question. How do you answer that question? Where do you look? How long does it take? Now, let’s search for one of the hundred traits that implement the function you’re looking at. Oh, what’s a HashMap? Is it somewhere from the standard library, or did they use a random third-party crate? Better scroll back up to the top of the file to find out!

See, there are good libraries and bad libraries. I happened to pick a bad one, but I presume a “good” library would have a simpler codebase, reasonably documented sources, etc etc.

Look, I understand, you get what you pay for, and I did use a random crate recommended by a random Redditor. But these Rust libraries seem to be “coping” with the complexity introduced by the language. In many cases they push against certain features, in other cases they embrace them. Why write an if statement when you can use .map() on a bool value and get the thing you want in one line of code? Maybe you don’t want that complexity and in your library such uses of map is banned.


I was pleasantly surprised (again) by how any random piece of Odin code is reasonably readable. You start in a place and you can follow the chain of function calls, or value declarations to arrive where you want. The functions can’t afford to not do anything. Each function does something and you can tell exactly what.

From my experience of being around Odin contributors I did know some of the design decisions and the way the language was designed. And I disagreed with them. But guess what, all that suffering and verbosity, it pays off at the end. It pays off for other people reading your code. And it pays off when you want to contribute with someone who has some disagreeing views (at least I imagine, I never tried).

I tried reading ols source code, out of curiosity. It was so surprising to me how it did document synchronization. Now, take this: It took me one line of code to figure that out.

if document := &document_storage.documents[uri.path]; document != nil {

Okay, so the documents field is accessed with uri.path, which seems like it could be a string, which means that documents is a map. I didn’t see any mutex locks, so this tells me the server process is single-threaded. So there is an in-memory map of files in the project. If you look at the else branch of that if statement you’d also find out that the documents that are stored on the filesystem are eventually loaded into memory. By looking at the definition of the document you see the client_owned field which tells us that the document does have the capability of being removed from the store (You’d need to understand document synchronization of LSP protocols to get that, but otherwise trivial to figure out)


This is a great example of how so much can be said so briefly if you keep it simple. I don’t think that many Odin codebases are good, but from experience reading, I can tell you most of them are readable.

11 Likes