Death by design patterns, or On the cognitive load of abstractions in the code

It&#x27;s not the number of abstractions, but the quality of abstractions. If abstractions reduce cognitive load, they are good. If abstractions increase cognitive load, they are bad. Often times good abstractions are obvious within the problem domain.<p>To this end, I think Haskell, in its pursuit of the purest, can lead to incredibly-high cognitive load abstractions that make reading code daunting. It feels good when writing it, but feels awful when reading it. Sometimes applying the DRY principle can be bad if the thing you are generalizing will lead to higher cognitive load for people referencing it.<p>Also I think abstractions vary in quality depending on the language the abstraction is embedded in. Functional paradigms in C++ are thorny to work with; even though functional paradigms are good abstractions in general, if the language doesn&#x27;t support it first-class (i.e. the cognitive load of using them is high), then they are not good abstractions.<p>You can also consider maps in a language like Clojure, where maps are almost &quot;zero-class&quot;; it&#x27;s like the language was built for maps. Nested maps have incredibly low cognitive load in Clojure (not only because the syntax supports it, but also because functions are standardized). Nested maps in Common Lisp, however, are not as nice as those in Clojure; you have to import non-standard libraries in order to deal with them (and even more obscure libraries to support Clojure-like read macros).<p>The key question is: when someone else reads this code, how much do they need to &quot;reconstruct&quot; the context? Can they get away with not reconstructing the context? And if they need to, how fast can they do so, via appropriate naming, comments, and types?

Worst offender for me is when I can&#x27;t access the implementation by just clicking on the type or variable, because it is an interface.<p>For example with dependency injection in languages where devs put Interfaces in constructors and some magic injects the Class that satisfies that Interface at runtime. When you click the type or variable, the IDE opens the Interface file which is just a bunch of function signatures, no implementation. It&#x27;s infuriating when all you want is to see some concrete code. You just want to see exactly what code is being executed and then carry on with your day.<p>I get the benefits of dependency injection but most of the times a single class implements that interface and yet i&#x27;m forced to scavenge the code to find it. I also know some tooling is powerful enough to list the Classes that satisfy that Interface. But it&#x27;s not perfect and it&#x27;s still a layer of indirection adding to my cognitive load.

For me, peak-design-pattern hit right about the time I worked on two different JVM-in-Java projects (2002-ish and 2008-ish). The problem, I finally realized, is that Java programmers are taught that every class is a special snowflake in need of armor and adornments. A good Java class should be honking and hollering! It should <i>never</i> expose a field, <i>never</i> have coupling with another class that couldn&#x27;t be interposed upon, and should <i>always</i> factor commonality into a superclass. At a minimum it should have fifteen methods, repeat the same names at least 7 times each, and be JavaDoc&#x27;d to the point your eyes are bleeding. Even if it just holds three fields and does nothing at all. ESPECIALLY IF IT DOES NOTHING AT ALL. It must pretend to be important! It should be long enough that you spend most of your time scrolling. If you aren&#x27;t scrolling, you aren&#x27;t coding!<p>What. A. Nightmare. It&#x27;s like trying to build an internal combustion engine and every moving part has three extra degrees of freedom, in case you wanted to pull a piston out in the middle of the freeway and use it to wipe your windshield! <i>Just in case</i> you want to do that, a piston can also function as a wheel, a cigarette lighter, or a potted plant. And of course it has the, ahem, <i>armor</i> (?) to do all of that. In fact, every nut and bolt and rod and wire has extra armor on it. They aren&#x27;t bolted together, they are held with miniature six-axis robot arms, just in case. And everything has plating. Thick metal plating. Bullet-proof plating. Everything indestructible. Getters and setters everywhere! Can&#x27;t you see how much better they make things! The design is so much better with getters and setterrrrss!<p>Needless to say, I don&#x27;t write code like that anymore. I prefer to write in Virgil, to make my fields public and immutable, initialized in the constructor or the anonymous zone, and when I need six classes to cooperate to do a job, they do, and they don&#x27;t put armor on for friends. Private applies to a file, everybody&#x27;s friends there, no surprises.<p>But I don&#x27;t expect anyone to follow me or worship it. I won&#x27;t claim amazing design skills. Just trying to make things work without a lot of extra work or surprises down the line.

One of the strangest ironies of my career is that the smartest developers often write the worst code. Their perfect memories enable them to effortlessly work with infinite layers of abstraction and write the most clever solutions imaginable to any problem.

I find these arguments going back in circles and concluding nothing.<p>All teams are different, and a good rule of thumb is to write code the least skilled or experienced person can understand on its own without guidance. Since teams vary so do these limits change. I had teams where it would&#x27;ve been odd to even try use any abstraction, let alone algebraic data types, and teams practicing lots of abstraction and architectural patterns all on top of functional effects. The teams widely different in proficiency of the best and weakest members and so did the codebase patterns.<p>It&#x27;s like in sports, different teams demand different approaches because the qualities and proficiencies differ, there are no universal truths but solutions that fit better different teams.

OP, I think you’d really enjoy the book “A Philosophy of Software Design” by John Ousterhout. It discusses this topic at length. With respect to reducing complexity, you pretty much drew the same conclusion he did.

In C++ the over-abstraction starts in your first lessons. I know and understand all the arguments, but I will never type this:<p><pre><code> std::cout &lt;&lt; &quot;You have &quot; &lt;&lt; itemCount &lt;&lt; &quot; items of type &quot; &lt;&lt; itemType &lt;&lt; &quot;.&quot; &lt;&lt; std::endl; </code></pre> When I could do this:<p><pre><code> printf(&quot;You have %d items of type %s.\n&quot;, itemCount, itemType.c_str());</code></pre>

I’m just a guy, so take what I say with a grain of salt.<p>This problem is broadly solved by a combination of domain-driven design (DDD) and functional programming (FP).<p>Yes, I know you’re tired of hearing about FP and you think FP engineers are all white bearded monad salespeople. I don’t care.<p>Odds are, if you’re an engineer, you’re not doing purely abstract work: your code has some correspondence to “stuff in the real world”. FP is unencumbered by the class&#x2F;object model and you can abstract over anything trivially using plain old functions: don’t “choose” your abstractions, use these, and your domain models, to figure out what the correct&#x2F;real(est) abstractions are. It’s not so much about too much or too little abstractions, it’s about how suitable the abstractions are.

No abstractions turns to spaghetti Too many abstractions turns to spaghetti<p>I don&#x27;t think the answer is one or the other at all like the blog post is implying. I think his previous conclusion of a threshold makes more sense. Perhaps though they have chosen the wrong abstractions and hence the confusion

He does not mention that &quot;linear&quot; code are much more grep-able than fancy pancy code. Even such simple things as error messages as string literals in the code makes your life so much easier.<p>A degenerate case of grep-able code is e.g. virtual methods for some class and derived types that share name with methods of another class and derived types.<p>I also distastes code with so much dynamicness that you have no clue where stuff happens. I really like long functions that do many things one thing after another.

This seems like a good place to share a horrific experience I&#x27;m currently enduring:<p>I recently took over a a Django API + React front end project.<p>What should should have been a basic CRUD application with some calendaring and video calling added turned into a nightmare and costs of over a million dollars for my client.<p>I&#x27;m a Rails and iOS dev mostly, so I have a bias, but here we go:<p>1) Using GraphQL for a business process CRUD app is a nightmare. Building on Django&#x27;s ORM with Graphene, then on the frontend with Apollo Client, Queries&#x2F;Mutations, and React with some Redux mixed in is a nightmare of hard to know database and business logic paths.<p>2) On the Django side, having their Views and Models (mostly Models) handle business logic, and then constructing a Graphene based GraphQL layer to be consumed by another layer GraphQL Queries&#x2F;Mutations via React is a mess, for what is essentially a bunch of forms on the frontend<p>3) Splitting out React Components into Atoms&#x2F;Molecules&#x2F;Organisms&#x2F;Pages&#x2F;Templates and more has been a nightmare to work with. Seriously - do you really need to build an Atom for a button that you pass the title text too?<p>The whole project is impossibly fragile.<p>Say what you will about Rails, but you can build a robust and functioning CRUD app that solves business problems without the need for developers to hack through a jungle of abstractions!<p>Sorting this all out for client has almost killed me and burned me out!

I&#x27;ve had the pleasure to work with an immensely talented developer who would spam unnecessary patterns all over the codebase, to the point where it required several coffees just to go through a single branch of domain logic. Even the IDs of his aggregates were classes.<p>At the same time, though, I feel very disheartening that at my current company devs ignore what even &quot;aggregate&quot; means, and don&#x27;t have any kind of clue about patterns and higher concepts in general. I really miss smart and educated people in IT.

One thing I have to say about this is that the fact they did this with a bunch of Python code is probably a huge part of why it didn&#x27;t go well. Abstracted Python code drives me crazy because, in part because of the dynamic and typed nature of Python, the support is so poor for then navigating around it afterwards.<p>Compare to Java and with single keystrokes I can navigate up the type hierarchy and bring up a full display of every class implementing an interface. With a couple more keystrokes I can rename a function in the base class and update all the implementors, globally across hundreds of thousands of lines of code. And in Eclipse this happens nearly instantly with 100% fidelity (I assume in other IDEs too). I can move around the codebase with so much ease. As soon as I hit Python code like this I&#x27;m completely lost.<p>I see people complaining all the time about IDEs (if you need an IDE then your code is bad) and then also about design patterns and abstraction and I do see a connection in that yes, if you need to scale complexity there is a fundamental aspect of that whereby you need a more structured approach to how you are building things and the underlying tools that are supporting that.

When I took a software engineering course, they talked about the benefits of &quot;decoupled code,&quot; &quot;dependency injection,&quot; and &quot;abstractions,&quot; but when it came to an actual tactical explanation of these things, or method of recognizing highly coupled code my education fell woefully short.<p>Tactically speaking, if you don&#x27;t abuse the global scope (class methods&#x2F;singletons are abuses of the global scope), don&#x27;t have circular dependencies, don&#x27;t have &quot;intialization&quot; methods called after constructors, and most important of all, don&#x27;t call non trivial functions in constructors, then your code is probably reasonably abstracted.<p>More importantly than being abstracted, it is probably absolutely boring and trivial to unit test.

It took us a long time as an industry to recognize that popularity of “design patterns” was due to problems with languages. And the best fix is to improve the language.

The cognitive load increases the furthest away you get from the problem you&#x27;re trying to solve.<p>I&#x27;ve worked with some really smart people that couldn&#x27;t program themselves out of a 24hrs challenge because they went deep in lalaland with patterns up the wazoo and didn&#x27;t just consider what the program needs to do.<p>A program is a set of instruction for a computer to do stuff. It takes data in, does stuff to it, and pushes it out. Whether you&#x27;re doing a UI or an automated landing system, it&#x27;s all the same. In one case, you&#x27;re waiting for user input to do stuff with it, on the other you&#x27;re reading sensors at a high frequency and affecting control inputs as a feedback loop.<p>Patterns should only be used if they actually solve a problem. E.g. the command pattern in systems that require Undos.<p>The simplest way to manage complexity in any program is to manage state carefully. Avoid global state, and use as much pure functions as you can. The net effects of this has been evaluated ad-nauseam and the results are clear: easier code to reason about, easier to parallelise, easier to test and less cognitive load.<p>Over-using patterns and abstractions is throwing cash in a pit. The harder a system becomes to reason about or change, the more it will cost to maintain.<p>Over-abstraction will result in<p><pre><code> main() { application_here() } </code></pre> which might look good in reviews, but the metrics won&#x27;t add up.

&gt; Now I introduce abstractions only if I decide that the future reader could confidently modify the code without looking at the implementations<p>Going full no true scotsman, but is it really an abstraction if that property does not hold true? Isn&#x27;t the author essentially arguing against leaky abstractions, which should self-evidently be a bad idea? The problem of course is that developers do not always have the prescience to predict if an abstraction will be leaky or not.

Reminds me of the worst code-base that I ever worked on...<p>Start with Java, but don&#x27;t work in Java directly. Add a layer of meta-programming on top. In this case it was an aspect-weaving system that allowed injecting methods into classes. By itself that would not have been too harmful, but this system had been used at scale, for more than a decade. The result was the emergent effect of aspect weaving on a code-base, which I have not seen before. The entire code-base had been splintered into thousands of small pieces that only existed to be injected into other contexts. It was very strange code.<p>The aspect-weaving system worked as an extension to the parser, so that all of the code written in it was essentially action rules for the parser. Data was constructed as synthetic or inherited attributes in the parse. The &quot;hairy control flow&quot; that is normally eliminated after the initial parsing phase existed in every pass in every part of the compiler. Essentially parsing never finished, as even late in the code-generation backend we were still tracing the emergent effect of grammar production rules.<p>Layered on-top of this was a pattern-heavy approach that tried to eliminate all remaining structure, shape and form. Days could be spent digging through scaffolding and layering code to try to find the pieces of functionality that went together to handle a particular construct or feature.<p>The layers of maintained- and generated- code meant that nobody actually knew how large the system was. I spent an afternoon trying to count it properly and I think my estimate of 1.5m lines was probably the closest that we had come.<p>I still have nightmares occasionally, but they are becoming less frequent over time.

Otherwise known as “your CS degree has shockingly little to do with this god forsaken login page we’re designing”<p>I’ve had so many long conversations with early-mid career developers that the stupid code being written will have a shelf life about as long as a head of lettuce. And that the “best” solution is typically the simplest, shortest, and can be written the quickest.

This article made me think of this blog post:<p><a href="https:&#x2F;&#x2F;mikehadlow.blogspot.com&#x2F;2012&#x2F;05&#x2F;configuration-complexity-clock.html" rel="nofollow">https:&#x2F;&#x2F;mikehadlow.blogspot.com&#x2F;2012&#x2F;05&#x2F;configuration-comple...</a><p>I prefer the old version or the pre over-refactored code better too, I can at least understand it.<p>I&#x27;ve noticed that when control flow is abstracted away at runtime for flexibility of future changes just in case we need to handle other cases in the future, the code starts to become difficult to reason about.<p>When people extract everything out until you have hundreds of low signal-to-noise files.<p>I think it&#x27;s a reaction to team based software delivery, where multiple people need to work on different layers independently and separately, but when you&#x27;re working solo, a dense codebase you can fit in your head is a lot more enjoyable.<p>Maybe the size of the codebase determines this.

Starting around the mid 2010s I think, I started seeing needless use of &quot;Design Patterns&quot; all over the place (mostly by CS graduates). Factories, adapters, observers in places where it was just plain overkill and needless extra lines of useless code.<p>I started referring to it as cargo-cult programming.

Simple code is like the Zen ideal. Direct seeing, direct apprehension. It beats any abstraction. It&#x27;s right there.<p>Like, we could almost have our ideal UI be a dozen lines of code (in some kind of CLIish dealy) , exposed for twiddling.<p>It would be the ultimate in informativeness, control and flexibility.

Given a domain, code generally changes similarly. For example: You have an app that interfaces with a scale to weigh widgets. At first you support one scale and so you just write code to solve the problem of reading the weight and sending it to the weight processor. After some time, there is a new scale. You now add some abstraction so that they both report a generalized weight message to the weight processor. When you later have to add a third, because you have that generalization, you can tell a new Junior dev &quot;just follow what the code is already doing&quot; and they should have no problem doing just that and add support for the third scale.<p>That is enough abstraction.

I don&#x27;t have the large code base experience, so I&#x27;m talking a bit out of line.<p>However, contra OO, I submit that keeping the data orthogonal to the methods is a win.<p>Restated, I haven&#x27;t seen much win with objectifying everything and having a huge object inheritance tree. Probably useful in some domain.<p>Recently looking at botocore. There are no classes for AWS services; just a &quot;database&quot; of JSON documents enumerating &quot;shapes&quot; and &quot;operations&quot;, and then some wrapper classes that dynamically instantiate classes where needed.<p>Feels as though AWS may be on to something, though doubtless their server-side code is non-trivial.

&gt; At some point I worked on a Python product written by a person with some good business knowledge, but essentially not a trained developer. They handled our team a bunch of cron-scheduled Python scripts that somehow implemented a complex data processing pipeline and our job was to maintain those. I remember my horror of looking at the code which had zero abstractions and essentially written as a bunch of linear scripts with copy-pasted bits of logic all over the place. Of course, our team has decided to bring some order to that. We have rigorously created abstractions for individual business logic workflows, implementations of those abstractions, factories to instantiate them, and more, and even more on top of that. Fast-forward a couple of months, I wasn’t working on a product for some time and then came back on the team. I looked at the code and I came to realization: the older version better. I had no idea what new code did. Instead of linear logic I had to jump between interfaces, their implementations and a bunch of other abstractions to gather together a complete understanding of the overall implementation. The voice of an experienced developer in my head said: “chosen poorly abstractions are here”. But another one annoyingly replied: “what does it mean to be a poorly chosen abstraction?”.<p>Unfortunately this is a very commonly observed difference between &quot;software engineers&quot; and &quot;business people who write code&quot;. The latter want to get a job done, while the former are often looking to implement engineering doctrine that may not be relevant to the problem at hand.

The fundamental problem, I think, is that software is by definition a way to create abstractions. And there are way too many incentives to complicate these abstractions. And on top of that, these complications have inertia. Once people learn they can gain prestige, job security and self importance by learning and multiplying abstractions, you have a runway process.<p>Complex systems evolve by brute forcing their problem space during a boom and pruning the non-viable inroads during a bust. That means a lot of agents will be stuck building dead-ends only to get wiped at some point. That&#x27;s why meta cognition is so important. We are not blind agents, we are a complex system ourselves. We are capable of internalizing giant swats of symbolic representations of system archetypes. We are capable of teleological behavior. Do it people. You can learn computer science and preempt a life of being mired by abstractions that won&#x27;t lead anywhere.<p>Sadly greed lead us astray too often.

In real world problems, there are many different constraints, mixed in with legacy code and tests along with many new requirements. It&#x27;s hard to wrangle through all of those 1000s of lines of code no matter how you slice it, abstractions or not. I think sometimes people just want to vent that if it&#x27;s hard that there MUST always be a better way. That&#x27;s not always the case.<p>It&#x27;s not gong to get fixed by just thinking about cognitive load. It&#x27;s a very delicate balance: increasing cohesion and encapsulation, adding robust tests, also adding new features, not spending ungodly amount of time refactoring, being mindful of how easy it is to review etc. Even cognitive load is not the right way to look at it. If the abstractions give you very desirable guarantees in terms of performance and correctness, you need to consider it too.

Design patterns reduce cognitive load, to those who know and understand the design patterns. For those who don&#x27;t, their cognitive load is increased. That&#x27;s why so many people so there&#x27;s more to learning how to program than learning a programming language and its most popular libraries. You need to learn the design patterns too. It&#x27;d do you well to also know some anti-patterns. After all, it&#x27;s useful to know what not to do as well as it is what to do.<p>Once you&#x27;ve mastered the most useful design patterns applying to your problem space, you can then focus on learning the architectural patterns.

The idea that you don&#x27;t need design patterns in smaller code bases is so strange to me. Design patterns are not some mechanisation designed by Big Code to get in your way. We call them patterns because they are similar structures that tend to reappear time after time in many codebases. Design patterns just gives them a vocabulary and a consistent(ish) style.<p>If you&#x27;re working on smaller code bases and you&#x27;re not seeing design patterns emerge I would strongly question what&#x27;s going on (or whether you understand patterns).

The problem with abstractions (in code) is in their purpose - &quot;Hide the details&quot;. You can create an abstraction that hide the details really well but this also means that it makes it really hard&#x2F;convoluted to find the details when required. Also, usually you don&#x27;t have just one abstraction, instead you have layers of abstractions and that makes things more complicated.

With regards to abstractions, the perceived quality of code depends heavily on who will be expected to read it. &quot;Principle of least surprise&quot; isn&#x27;t universal, it&#x27;s subjective because you&#x27;re hiding complexity not actually making things less complex. If an abstraction feels natural to the person reading it, they will find the code easy to read.

Weird take, design patterns take off cognitive load. It&#x27;s easier to say. Use an observe or strategy pattern or adapter pattern. In most sufficiently large OO code bases, folk end up implementing design patterns sometimes and often poorly, without knowing the names for them.

I work on multiple small multiplayer games. We have shared modules across the front and back end. We split our code into what is game specific, what is library level and what is framework level.<p>We got the simple stuff right the first time, but it&#x27;s not until project #3 where we are actually building the framework properly.<p>A library exposes utilities that an application chooses to use.<p>A framework constrains the application to a precise system and offers a lot of power within that system.<p>Frameworks are the most risky to write.<p>You should always prefer libraries over frameworks until you are certain not only of the problem domain, but the future of the company.<p>Our first project we really just prioritized features and time to market.<p>When I was designing the golang based backend for our newest project, I spent almost 2 weeks iterating on the design of the framework. The set of constraints around what an API call would do. I implemented a system for syncing JSON objects between the client and server. A system I had been thinking about for 4 years. It works really well and felt good to implement.<p>The constraints I created offer us a lot of power. Logs are automatic and consistent. We can run analytics on the diff of every single player interaction. The constraints guide developers into writing performant code.<p>However there are flaws in the framework. Those flaws could become landmines. Or there are theoretical designs that cannot be represented by the framework, and I have a strong opinion on how to extend the framework to support that. Another dev might implement that new feature in a spaghetti code way. But I can&#x27;t really justify spending another week iterating on those flaws.<p>When I was pondering where the line is of how long to iterate on the framework level, I was reminiscing fondly of how simple the first products backend is. Each API call written as a unique snowflake, with all its reads and writes and errors in a straight line, and divided into simple functions with no rules. But then I remember the flaws, the database load is high, there are reads and writes going on inside deep function calls. Reading the same record multiple times in an API call. The lack of consistency in the response structure and how the client would deal with that. The lack of completeness of the logs. The inability for us to comprehensively analyze our players data.<p>Abstractions are useful. It&#x27;s hard to get them right. You&#x27;re better off dumping all the Legos on the floor before you try to sort them.

The cleverest code is, in my experience, the simplest. Anything else isn’t clever, it’s just showing off.

Should have written it in rust, it has ZERO cost abstractions.

Abstraction if necessary but not necessarily abstraction.

Author provides a good example. Linear scripts are a horror to maintain but a project with too many abstractions are a horror to understand.<p>I&#x27;d rather maintain the latter because I just need to understand the code once and figuring out abstraction layers is fun at the cost of my employer&#x27;s dime.<p>&gt; the older version better<p>Better in what aspect? Better to maintain? Better to debug? Better in solving the business needs? If the answer is all of them then congrats you have poorly done refactoring.