Abstractions: Does your code tell a good story?

I have always been fascinated with how we structure the code and architecture of our systems. Over the years I have found it fascinating to see the fashions change on both surface arguments (e.g. tabs vs. spaces, foo_bar vs. camelCase), and architecture issues (e.g. granularity of services).

I often wonder how much information cascading occurs. We see the side effects when noticing a change in approach that people consider to be a revolution (Ajax, iOS, Docker) compared to one where people believe it is a failure (*cough* EJB *cough*).

The Story

I have often been happy with code that reads well like a story. This is one of the reasons why I disliked the Java of old, as it felt like I was always getting in the way of the story with boilerplate for the computer.

I felt like I was writing sentences such as:

Dion (a person) enjoyed (verb) eating (adjective) food (a noun)

My brain best connected with languages such as Ruby where I could distill the language down.

This is why I have always been fascinated with literate programming.

The Abstraction

What makes coding slightly different to a story though is the domain knowledge of the abstractions.

When I read a book, the majority of the words encompass an abstraction that I already understand. I am then able to chain these together to progress through it from start to finish.

With coding, unless it is writing something that you have a complete model of in your brain (very rare for me since most of the time I am creating something new), you are building a layer of abstractions from primitives. Since this is software, you have a different level of constraints. On the one hand the primitives that you have may be constraining, but on the other hand you can do things that are closer to the mental than the physical (which separates this work from traditional engineering).

If I am reading someones code, I need to get the model into my mind while reading it, which isn’t always easy, especially as you keep nesting abstractions.

This is why we dislike leaky abstractions. When they leak you need to keep more of the abstraction chain in your head.

It is through this lens that I personally enjoy technology such as React. The more I can hide in a <Component> and compose on it the better.

It is also why I often enjoy doing some test first like development to root out an API from the consumer end (top down vs. bottom up). Some problems are easier to reason that way vs. from primitives up. This lets you play the role of a user of the abstraction and it is often a good idea to have the knowledge of a layer above and beyond you, as Glenn always said:

"Developers should always understand one layer of abstraction below their everyday work” /by @glv

— Dion Almaer (@dalmaer) November 19, 2013

Our short term memory

We keep learning about our learning, and it is fascinating. There have been interesting studies around how much data we can keep in working short term memory.

One of the keys is around chunking. When it comes to remembering a string of numbers, it is obvious that you would have a better chance remembering “CIAFBIABCCNN” compared to “AURNFUQTPZYJ” because you can chunk the letters into CIA, FBI, ABC, CNN. Techniques for memorizing packs of cards are all about having an abstraction for each card and then building a story around it: “The queen with the diamond ate at the park with four dogs”.

Do you think that your system tells a story in a way that you can keep the model better in your mind?

This is one of my quests. Mapping a great story to my software so a team can own it and talk at the highest levels possible.