This applies to user experience as well. I&#x27;ve seen designers focus on number of items or number of clicks when mental effort &#x2F; cognitive load is what matters. Sometimes picking from a list of 50 links is easier. Sometimes answering 7 yes&#x2F;no questions is easier.

Depends on how you define smart. I worked at a place where income was directly tied to the quality of the ML models. Building what people love wouldn&#x27;t have been the best strategy there.

Only if your goal is to be an entrepreneur. Not everyone chases that goal nor considers success in that fashion.

&gt; The companies where we were like ”woah, these folks are smart as hell” for the most part failedBeing clever, for the most part, almost never buys you anything. Building a cool product has nothing to do with being particularly smart, and scaling said product also rarely has much to do with being some kind of genius.There&#x27;s this pervasive Silicon Valley throughline of the mythical &quot;10x engineer,&quot; mostly repeated by incompetent CEO&#x2F;PM-types which haven&#x27;t written a line of code in their lives. In reality, having a solid mission, knowing who your customer is, finding that perfect product market fit, and building something people love is really what building stuff is all about.At the end of the day, all the bit-wrangling in the world is in service of that goal.

&gt; Cyclomatic complexity seems one indicator, but architectural complexity needs to be clarified. I agree that how much modules expose to each other is one trait, but again, needs clarification. How do you intend to go about this?Too much to summarize in a comment, I recommend reading the 3-blog series linked above. Architectural complexity is pretty well defined and we have an exact way to measure it.Unfortunately there’s little industry tooling I’ve found to expose this number on the day-to-day. There’s 1 unpopular paid app with an awful business model – I couldn’t even figure out how to try it because they want you to talk to sales first &#x2F;eyeroll.I have some prototype ideas rolling around my brain but been focusing on writing the book first. Early experiments look promising.There IS backing from cognitive research too – working memory. We struggle to keep track of more than ~7 independent items when working. The goal of abstraction (and this essay’s cognitive load idea) is to keep the number of independently moving or impacted pieces under 7 while working. As soon as your changes could touch more stuff than fits in your brain, it becomes extremely challenging to work with and you get those whack-a-mole situations where every bug you fix causes 2 new bugs.

I’ve been interested in the same topic for a while now and the most difficult part, when explaining the concept to other programmers and defending against it in coding standards&#x2F;reviews, is how to prove that cognitive load exists.Cyclomatic complexity seems one indicator, but architectural complexity needs to be clarified. I agree that how much modules expose to each other is one trait, but again, needs clarification. How do you intend to go about this?Been thinking about custom abstractions (ie those that you build yourself and which do not come from the standard libraries&#x2F;frameworks) needed to understand code and simply counting them; the higher the number, the worse. But it seems that one needs to find something in cognitive psychology to back up the claim.

This is true and valuable, but it&#x27;s worth mentioning that some aspect of cognitive load is subjective. The code I write is always lower cognitive load to me than anyone else&#x27;s code, even if my code has more cyclomatic complexity and code smells, because I&#x27;ve built up years of neural representations dedicated to understanding my favored way of doing things via practice and repetition. And I lack the neural representations needed to quickly understand other people&#x27;s code if they approach things differently, even if their approach is just better.This is not to say we should keep practicing our bad habits, but that we should practice good habits (e.g. composition over inheritance) as quickly as possible so the bad habits don&#x27;t become ingrained in how we mentally process code.

We can measure and quantify this cognitive load! I’ve been researching this for a book and have found some really cool research from ~10 years ago. It seems people stopped thinking about this around when microservices became popular (but they have the same problems just with http&#x2F;grpc calls instead).There are two main ways to measure this:1. Cyclomatic&#x2F;mccabe complexity tells you how hard an individual module or execution flow is to understand. The more decision points and branches, the harder. Eventually you get to “virtually undebuggable”2. Architectural complexity measures how visible different modules are to each other. The more dependencies, the worse things get to work with. We can empirically measure that codebases with unclear dependency structures lead to bugs and lower productivity.I wrote more here: <a href="https:&#x2F;&#x2F;swizec.com&#x2F;blog&#x2F;why-taming-architectural-complexity-is-paramount&#x2F;" rel="nofollow">https:&#x2F;&#x2F;swizec.com&#x2F;blog&#x2F;why-taming-architectural-complexity-...</a>The answer seems to be vertical domain oriented modules with clear interfaces and braindead simple code. No hammer factory factories.PS: the big ball of mud is the world’s most popular architecture because it works. Working software first, then you can figure out the right structure.

Agreed.Regarding some of the ‘layered architecture’ discussion from the OP, I’d argue that having many modules that are clearly defined is not as large a detriment to cognitive load when an LLM is interpreting it. This is dependent on two factors, each module being clearly defined enough that you can be confident the problem lies within the interactions between modules&#x2F;components and not within them AND sharing proper&#x2F;sufficient context with an LLM so that it is focused on the interactions between components so that it doesn’t try to force fit a solution into one of them or miss the problem space entirely.The latter is a constant nagging issue but the former is completely doable (types and unit testing helps) but flies in the face of the mo’ files, mo’ problems issue that creates higher cognitive loads for humans.

With LLM generated code (and any code really) the interface between components becomes much more important. It needs to be clearly defined so that it can be tested and avoid implicit features that could go away if it were re-generated.Only when you know for sure the problem can&#x27;t be coming through from that component can you stop thinking about it and reduce the cognitive load.

&gt; I’d really love to have a discussion on how these heuristics of software development change with the likes of Cursor&#x2F;LLM cyborg coding in the mixI would also be interested in reading people’s thoughts about how those heuristics might change in the months and years ahead, as reasoning LLMs get more powerful and as context windows continue to increase. Even if it never becomes possible to offload software development completely to AI, it does seem at least possible that human cognitive load will not be an issue in the same way it is now.

Looks like a solid post with solid learnings. Apologies for hijacking the thread but I’d really love to have a discussion on how these heuristics of software development change with the likes of Cursor&#x2F;LLM cyborg coding in the mix.I’ve done an extensive amount of LLM assisted coding and our heuristics need to change. Synthesis of a design still needs to be low cognitive load - e.g. how data flows between multiple modules - because you need to be able to verify the actual system or that the LLM suggestion matches the intended mental model. However, striving for simplicity inside a method&#x2F;function matters way less. It’s relatively easy to verify that an LLM generated unit test is working as intended and the complexity of the code within the function doesn’t matter if its scope is sufficiently narrow.IMO identifying the line between locations where “low cognitive load required” vs “low cognitive load is unnecessary” changes the game of software development and is not often discussed.

One way that I explain cognitive load to people unfamiliar with the term is to imagine crossing a lawn that has both autumn leaves and dog poop, and picture how much more mental energy one expends when trying to not step on dog poop.

I don&#x27;t think largeness is the problem. It&#x27;s language design. C++ is just really badly designed. I&#x27;d be very happy with a very large language that takes a long time to get familiar, if all the features in the language are well designed. IMO the current developer landscape is all about &quot;fast onboarding&quot;, but that is the totally wrong metric to optimize for. To me it&#x27;s the difference between someone walking and an airplane. Sure it&#x27;s very easy to just start walking, you ain&#x27;t going to go anywhere fast. On the other hand an airplane takes orders of magnitude longer to get going but once it does you won&#x27;t ever catch up to it by walking.

I think this works only up to the point where the language gets too large and starts creating extra cognitive load all by itself. For me, C++ is a good example of a language that has too many bells and whistles, if I have to stop what I&#x27;m doing to look up some weird syntax construct, then having all those extra features stops being useful.

Cognitive load is precisely why I love feature rich languages. Once you have internalized a language the features it has fall away in terms of cognitive load for me. In the same way I don&#x27;t think about how to ride a bike while I&#x27;m riding a bike.In most cases having a simpler language forces additional complexity into a program which does noticable add to cognitive load.

When the code needs to do something that it can&#x27;t do, there is a massive cognitive load associated with figuring out how to do something approximating it. When the language or a framework is associated with lots of &quot;how do I X&quot; questions, the answers to which are all &quot;completely rethink your program&quot;, that is evidence that the language&#x2F;framework is not reducing cognitive load.

Totally agree. I think the biggest and most important things a language designer chooses is what to disallow. For instance, private&#x2F;package&#x2F;public etc is one small example of an imposed restriction which makes it easier to reason about changing a large project because if e.g. something is private then you know it&#x27;s okay and probably easy to refactor. The self-imposed restrictions save you mental effort later. I also love lisps but am a Clojure fan. This is because in Clojure, 90+% of the code is static functions operating on immutable data. That makes it extremely easy to reason about in the large. Those two restrictions are big and impose a lot of structure, but man I can tear around the codebase with a machete because there are so many things that code &#x2F;can&#x27;t do&#x2F;. Also, testing is boneheaded simple because everything is just parameters in to those static functions and assert on the values coming out. I don&#x27;t have to do some arduous object construction with all these factories if I need to mock anything, I can use &quot;with-redefs&quot; to statically swap function definitions too, which is clean and very easy to reason about. Choosing the things you mr language disallows is one of the most important things you can do to reduce cognitive load.

&gt; Doesn&#x27;t mean it&#x27;s easy for another human to clearly see it.Why do you think that matters? If it&#x27;s not needed, then it should never have been there in the first place. If it helps to make the program readable by humans then it can be shown as part of the rendering of the program on a screen, but again, that should be part of the work the computer does, not the human. Unnecessary cognitive load is still unnecessary cognitive load regardless of the goal in whose name it is imposed.

No, as python and other languages amply demonstrate, the semicolon is for the compiler, not the developer. If the compiler is sophisticated enough to figure out that a semicolon is needed, it has become optional. That&#x27;s the OP&#x27;s point.

I disagree with the first point. Say, the compiler figured out your missing semicolon. Doesn&#x27;t mean it&#x27;s easy for another human to clearly see it. The compiler can spend enormous compute to guess that, and that guess doesn&#x27;t even have to be right! Ever been in a situation where following the compiler recommendation produces code that doesn&#x27;t work or even build?
We are optimizing syntax for humans here, so pointing out some redundancies is totally fine.

There are plenty of languages that don’t require semicolons and yet manage to avoid those issues: Clojure, Go, Odin…

Yes, semicolons are totally unnecessary. That’s why nobody who works on JavaScript has ever regretted that automatic semicolon insertion was added to the language. It has never prevented the introduction of new syntaxes to the language (like discussed here: &lt;<a href="https:&#x2F;&#x2F;github.com&#x2F;twbs&#x2F;bootstrap&#x2F;issues&#x2F;3057#issuecomment-5135562">https:&#x2F;&#x2F;github.com&#x2F;twbs&#x2F;bootstrap&#x2F;issues&#x2F;3057#issuecomment-5...</a>&gt;), nor motivated the addition of awkward grammatical contortions like [no LineTerminator here].

Great points. I strongly agree with your first point. Regrettably, I haven&#x27;t used any language that solves this. (But believe it&#x27;s possible, and you&#x27;ve demonstrated with one I haven&#x27;t used).I&#x27;m stuck between two lesser evils, not having the ideal solution you found:
1: Rust: Commits the sin you say.
2: Python, Kotlin, C++ etc: Commits a worse sin: Prints lots of words.. (Varying degrees depending on which of these), where I may or may not be able to tell what&#x27;s wrong, and if I can, I have to pick it out of a text well.Regarding boilerplate: This is one of the things I dislike most about rust. (As an example). I feel like prefixing`#[derive(Clone, Copy, PartialEq)]` on every (non-holding) enum is a flaw. Likewise, the way I use structs almost always results in prefixing each field with `pub`. (Other people use them in a different way, I believe, which doesn&#x27;t require this)

Semicolons are just an example, and a fairly minor one. A bigger pet peeve of mine is C-style type declarations. If I create a binding for X and initialize it to 1, the compiler should be able to figure out that X is an integer without my having to tell it.In fact, all type declarations should be optional, with run-time dynamic typing as a fallback when type inferencing fails. Type &quot;errors&quot; should always be warnings. There should be no dichotomy between &quot;statically typed&quot; and &quot;dynamically typed&quot; languages. There should be a smooth transition between programs with little or no compile-time type information and programs with a lot of compile-time type information, and the compiler should do something reasonable in all cases.

&gt; the compiler can tell you that there needs to be a semicolon right hereI can see that this is an annoyance, but does it really increase cognitive load? For me language design choices like allowing arbitrary arguments to functions (instead of having a written list of allowed arguments, I have to keep it in my head), or not having static types (instead of the compiler or my ide keeping track of types, I have to hold them in my head) are the main culprits for increasing cognitive load. Putting a semicolon where it belongs after the compiler telling me I have to is a fairly mindless exercise. The mental acrobatics I have to pull off to get anything done in dynamically typed languages is much more taxing to me.

Sure, changing the syntax is not something to be done lightly. It has to be done judiciously and with great care. But it can be a huge win in some cases. For example, take a look at:<a href="https:&#x2F;&#x2F;flownet.com&#x2F;gat&#x2F;lisp&#x2F;djbec.lisp" rel="nofollow">https:&#x2F;&#x2F;flownet.com&#x2F;gat&#x2F;lisp&#x2F;djbec.lisp</a>It implements elliptic curve cryptography in Common Lisp using an embedded infix syntax.

I agree up until the end. Languages that let you change the syntax can result in stuff where every program is written in its own DSL. Ruby has this issue to some extent.

It&#x27;s talking about lisp macros, idempotent languages, and a few other features of lispey languages. I&#x27;d suggest the book On Lisp, or Lisp in Small Pieces as good places to learn about it, but there are a ton of other resources that may be better suited to your needs.

Regarding Common Lisp, do you know of any articles that highlight the methods used to &quot;change the syntax and add new constructs so that the language meets the problem and not the other way around.&quot;

&gt; Another red flag is boilerplate. By definition boilerplate is something that you have to type not because it&#x27;s required to specify the behavior of the code but simply because the language design demands it. Boilerplate is always unnecessary cognitive load, and it&#x27;s one sign of a badly designed language. (Yes, I&#x27;m looking at you, Java.)The claim that LLMs are great for spitting out boilerplate has always sat wrong with me for this reason. They are, but could we not spend some of that research money on eliminating some of the need for boilerplate, rather than just making it faster to input?

I&#x27;ve had some C# code inflicted on me recently that follows the pile of garbage design pattern.  Just some offshore guys fulfilling the poorly expressed spec with as little brain work as possible.  The amount of almost-duplicate boilerplate kicking around is one of the problems.  Yeah it looks like the language design encourages this lowest common denominator type approach, and has lead into the supplier providing code that needs substantial refactoring in order be able to create automated tests as the entry points ignore separation of concerns and abuse private v public members to give the pretense of best practices while in reality providing worst practice modify this code at your peril instead. It&#x27;s very annoying because I could have used that budget to do something actually useful, but on the other hand improves my job security for now.

If some program can generate that code automatically, the need to generate it, write it to disk, and for you to edit it is proof that there is some flaw in the language the code is written in. When the generator needs to change, the whole project is fucked because you either have to delete the generated code, regenerate it, and replicate your modifications (where they still apply, and if they don&#x27;t still apply, it could have major implications for the entire project), or you have to manually replicate the differences between what the new version of the generator would generate and what the old version generated when you ran it.With AST macros, you don&#x27;t change generated code, but instead provide pieces of code that get incorporated into the generated code in well-defined ways that allow the generated code to change in the future without scuttling your entire project.&gt;others to come along and easily read&#x2F;modify something verbose without having to go context-switch or learn something.They&#x27;re probably not reading it, but assuming it&#x27;s exactly the same code that appears in countless tutorials, other projects, and LLMs. If there&#x27;s some subtle modification in there, it could escape notice, and probably will at some point. If there are extensive modifications, then people who rely on that code looking like the tutorials will be unable to comprehend it in any way.

&gt; Another red flag is boilerplate.I have to disagree. Boilerplate can simply be a one-time cost that is paid at setup time, when somebody is already required to have an understanding of what’s happening. That boilerplate can be the platform for others to come along and easily read&#x2F;modify something verbose without having to go context-switch or learn something.Arguing against boilerplate to an extreme is like arguing for DRY and total prevention of duplicated lines of code. It actually increases the cognitive load. Simple code to read and simple code to write is low-cost, and paying a one-time cost at setup is low compared to repeated cost during maintenance.

If the world put even a tenth of the effort into training Lisp programmers as it does into training Java programmers you would have no trouble marshaling an army of Lisp programmers.

&gt; Another red flag is boilerplate. By definition boilerplate is something that you have to type not because it&#x27;s required to specify the behavior of the code but simply because the language design demands it.Two things: 1) this is often not language design but rather framework design, and 2) any semantic redundancy in context can be called boilerplate. Those same semantics may not be considered boilerplate in a different context.And on the (Common) Lisp perspective—reading and writing lisp is arguably a unique skill that takes time and money to develop and brings much less value in return. I&#x27;m not fan of java from an essentialist perspective, but much of that cognitive load can be offset by IDEs, templates, lint tooling, etc etc. It has a role, particularly when you need to marshall a small army of coders very rapidly.

Completely agree! Common Lisp is truly the tool of the Gods.

Sure.  I understand why things are the way they are.  But that I don&#x27;t think that is a reason not to complain about the way things are.  Improvement is always the product of discontent.

The criticisms of Java syntax are somewhat fair, but it&#x27;s important to understand the historical context. It was first designed in 1995 and intended to be an easy transition for C++ programmers (minimal cognitive load). In an alternate history where James Gosling and his colleagues designed Java &quot;better&quot; then it would have never been widely adopted and ended up as a mere curiosity like Common Lisp is today. Sometimes you have to meet your customers where they are.It has taken a few decades but the latest version significantly reduces the boilerplate.

I don&#x27;t think you can have golden rules, if you do, you fall in the usual don&#x27;t do X, or limit Y to Z lines, etc.But what you _can_ do is to ask yourself whether you&#x27;re adding or removing cognitive load as you work and seek feedback from (possibly junior) coworkers.

This is true for exactly the same reason that no one algorithm compresses all types of data equally well.

My gripe with the post is that there is no objective &quot;cognitive load&quot; solution. Arguably this varies from 1 person to another.

I like (3) to be honest and the number of times it has poised any issue is virtually 0.

&gt; Unlike CL, there&#x27;s never a parser or an interpreter hidden in thereIve never ever run into this problem in the years of writing common lisp. Can you show me an example code that has this? I wager you cannot and you are writing poopoo about something you know poo about and want it to be true just because you are too lazy to move beyond knowing poo&gt; But this kind of power just isn&#x27;t conducive to maintainable code.I can usually run code decades old in common lisp. In fact this is one of its well known features. How much more maintainable can it possibly get :)

So with semi-colons, you have three basic options:1. Not required (eg Python, Go)2. Required (eg C&#x2F;C++, Java)3. Optional (eg Javascript)For me, (3) is by far the worst option. To me, the whole ASI debate is so ridiculous. To get away with (1), the languages make restrictions on syntax, most of which I think are acceptable. For example, Java&#x2F;C&#x2F;C++ allow you to put multiple statements on a single line. Do you need that? Probably not. I can&#x27;t even think of an example where that&#x27;s useful&#x2F;helpful.&quot;Boilerplate&quot; becomes a matter of debate. It&#x27;s a common criticism with Java, for example (eg anonymous classes). I personally think with modern IDEs it&#x27;s really a very minor issue.But some languages make, say, the return statement optional. I actually don&#x27;t like this. I like a return being explicit and clear in the code. Some will argue the return statement is boilerplate.Also, explicit type declarations can be viewed as boilerplate.. There are levels to this. C++&#x27;s auto is one-level. So are &quot;var&quot; declarations. Java is more restrictive than this (eg &lt;&gt; for implied types to avoid repeating types in a single declaration). But is this boilerplate?Common Lisp is where you lose me. Like the meme goes, if CL was a good idea it would&#x27;ve caught on at some point in the last 60 years. Redefning the language seems like a recipe for disaster, or at least adding a bunch of cognitive load because you can&#x27;t trust that &quot;standard&quot; functions aren&#x27;t doing standard things.Someone once said they like in Java that they&#x27;re never surprised by 100 lines of code of Java. Unlike CL, there&#x27;s never a parser or an interpreter hidden in there. Now that&#x27;s a testament to CL&#x27;s power for sure. But this kind of power just isn&#x27;t conducive to maintainable code.

<pre><code> % cat test.c
 main () {
 int x
 x=1
 }
 % gcc test.c 
 test.c:1:1: warning: type specifier missing, defaults to &#x27;int&#x27; [-Wimplicit-int]
 main () {
 ^
 test.c:2:8: error: expected &#x27;;&#x27; at end of declaration
 int x
 ^
 ;
 1 warning and 1 error generated.</code></pre>

You can reduce your Java boilerplate to annotations or succinct XML or whatever. Code generation is used a lot on the JVM.Can you show a real compiler message about such a semicolon?

&gt; But choosing Haskell or a lisp (maybe I can exclude Clojure somewhat) at work? No, no and no.I&#x27;ve been using CL at work for pretty much my entire career and have always gotten a huge amount of leverage from it.

I’m surprised to hear this from an avid Haskeller and I think it might give the wrong impression to those who are less familiar with Haskell. I’m sure you know this, but for the benefit of others, projects don’t have their own extensions, they just may or may not use some of the extensions provided by GHC. Anyway, that practice is now diminishing given the GHC2021 and GHC2024 “standards”, which just enable a fixed set of stable extensions.And regarding using specific compiler flags, well, projects almost never do that.

I dumped Haskell specifically because of its enormous cognitive load. All my time and energy went into Haskell and its endless quirks, leaving nothing for the business problem and its stakeholders.

The very same reasons you find CL to lower your cognitive load are why ultimately after 60 years all lisps have been relegated to niche languages despite their benefits, and I say it as a Racket lover. It raises cognitive load for everybody else by having to go through further steps into decoding your choices.It&#x27;s the very same reason why Haskell monocle-wielding developers haven&#x27;t been able to produce one single killer software in decades: every single project&#x2F;library out there has its own extensions to the language, specific compiler flags, etc that onboarding and sharing code becomes a huge chore. And again I say it as an avid Haskeller.Haskellers know that, and there was some short lived simple Haskell momentum but it died fast.But choosing Haskell or a lisp (maybe I can exclude Clojure somewhat) at work? No, no and no.Meanwhile bidonville PHP programmers can boast Laravel, Symfony and dozens of other libraries and frameworks that Haskellers will never ever be able to produce. Java?C? Even more.The language might be old and somewhat complex, but read a line and it means the same in any other project, there are no surprises only your intimacy with the language limiting you. There&#x27;s no ambiguity.

&gt; poor language designWe have an excellent modern-day example with Swift - it managed to grow from a simple and effective tool for building apps, to a “designed by committee” monstrosity that requires months to get into.

OMG, so much this.One of the biggest sources of cognitive load is poor language design. There are so many examples that I can&#x27;t even begin to list them all here, but in general, any time a compiler gives you an error and tells you how to fix it that is a big red flag. For example, if the compiler can tell you that there needs to be a semicolon right here, that means that there does not in fact need to be a semicolon right there, but rather that this semicolon is redundant with information that is available elsewhere in the code, and the only reason it&#x27;s needed is because the language design demands it, not because of any actual necessity to precisely specify the behavior of the code.Another red flag is boilerplate. By definition boilerplate is something that you have to type not because it&#x27;s required to specify the behavior of the code but simply because the language design demands it. Boilerplate is always unnecessary cognitive load, and it&#x27;s one sign of a badly designed language. (Yes, I&#x27;m looking at you, Java.)I use Common Lisp for my coding whenever I can, and one of the reasons is that it, uniquely among languages, allows me to change the syntax and add new constructs so that the language meets the problem and not the other way around. This reduces cognitive load tremendously, and once you get used to it, writing code in any other language starts to feel like a slog. You become keenly aware of the fact that 90% of your mental effort is going not towards actually solving the problem at hand, but appeasing the compiler or conforming to some stupid syntax rule that exists for no reason other than that someone at some time in the dim and distant past thought it might be a good idea, and were almost certainly wrong.

Totally agree with this and would add that cognitive load is not just a matter of the code before you, but a function of your total digital environment:<a href="https:&#x2F;&#x2F;vonnik.substack.com&#x2F;p&#x2F;how-to-take-your-brain-back" rel="nofollow">https:&#x2F;&#x2F;vonnik.substack.com&#x2F;p&#x2F;how-to-take-your-brain-back</a>Interruptions and distractions leave a cognitive residue that drastically reduces working memory through the Zeigarnik effect.

Then you need to make those functions public, when the goal is to keep them private and unusable outside of the parent function.Sometimes it&#x27;s easy to write multiple named functions, but I&#x27;ve found debugging functions can be more difficult when the interactions of the sub functions contribute to a bug.Why jump back and forth between sections of a module when I could&#x27;ve read the 10 lines in context together?

For unit testing those sub-sections in a clear and concise manner (i.e., low cognitive load). As long as the method names are descriptive no jumping to and fro is needed usually.That doesn&#x27;t mean every little unit needs to be split out, but it can make sense to do so if it helps write and debug those parts.

Why is that any easier than having comments in the code that describe each part? In languages that don&#x27;t allow closures, there&#x27;s no good way to pass state between the seven functions unless you pass all the state you need, either by passing all the variables directly, or by creating an instance of a class&#x2F;struct&#x2F;whatever to hold those same variables and passing that. If you&#x27;re lucky it might only be a couple of variables, but one can imagine that it could be a lot.

If the variables were clearly named, I wouldn&#x27;t have to read much at all, unless I was interested in the details. I reitrate: why does the length of the single function with no reuse matter?

&gt;why the hell would it be &quot;easier to read&quot; if I had to jump up and down the file to 7 different submethods when the function&#x27;s entire flow is always sequential?If the submethods were clearly named then you&#x27;d only need to read the seven submethod names to understand what the function did, which is easier than reading 100 lines of code.

Wouldn&#x27;t you jump to is_enabled to see what it does?That&#x27;s what I always do in new code, and probably why I dislike functions that are only used once or twice. The overhead of the jump is not worth it. is_enabled could be a comment above the block (up to a point, notif it&#x27;s too long)

If you&#x27;re literally using it just once, why not stick it in a local variable instead? You&#x27;re still getting the advantage of naming the concept that it represents, without eroding code locality.However, the example is a slightly tricky basis to form an opinion on best practice: you&#x27;re proposing that the clearly named example function name is_enabled is better than an expression based on symbols with gibberish names. Had those names (x, foo, bar, baz, etc) instead been well chosen meaningful names, then perhaps the inline expression would have been just as clear, especially if the body of the if makes it obvious what&#x27;s being checked here.It all sounds great to introduce well named functions in isolated examples, but examples like that are intrinsically so small that the costs of extra indirection are irrelevant. Furthermore, in these hypothetical examples, we&#x27;re kind of assuming that there _is_ a clearly correct and unique definition for is_enabled, but in reality, many ifs like this have more nuance. The if may well not represent if-enabled, it might be more something like was-enabled-last-app-startup-assuming-authorization-already-checked-unless-io-error. And the danger of leaving out implicit context like that is precisely that it sounds simple, is_enabled, but that simplicity hides corner cases and unchecked assumptions that may be invalidated by later code evolution - especially if the person changing the code is _not_ changing is_enabled and therefore at risk of assuming it really means whether something is enabled regardless of context.A poor abstraction is worse than no abstraction. We need abstractions, but there&#x27;s a risk of doing so recklessly. It&#x27;s possible to abstract too little, especially if that&#x27;s a sign of just not thinking enough about semantics, but also to abstract too much, especially if that&#x27;s a sign of thinking superficially, e.g. to reduce syntactic duplication regardless of meaning.

I find &quot;is_enabled(x)&quot; to be easier to reason about than<pre><code> if (x.foo || x.bar.baz || (x.quux &amp;&amp; x.bar.foo))
</code></pre>
Even if it&#x27;s only ever used once. Functions and methods provide abstraction which is useful for more than just removing repetition.

Yeah, I find extracting code into methods very useful for naming things that are 1) a digression from the core logic, and 2) enough code to make the core logic harder to comprehend. It’s basically like, “here’s this thing, you can dig into it if you want, but you don’t have to.” Or, the core logic is the top level summary and the methods it calls out to are sections or footnotes.

In recent years my general principle has been to introduce an abstraction (in this case split up a function) if it lowers local concepts to ~4 (presumably based on similar principles to the original post). I’ve taken to saying something along the lines of “abstractions motivated by reducing repetition or lines of code are often bad, whilst ones motivated by reducing cognitive load tend to be better”.Good abstractions often reduce LOC, but I prefer to think of that as a happy byproduct rather than the goal.

&gt;My principle has always been: “is this part a isolated and intuitive subroutine that I can clearly name and when other people see it they’ll get it at first glance without pausing to think what this does (not to mention reading through the implemention)”.I hold this principle as well.And I commonly produce one-liner subroutines following it. For me, 15 lines has become disturbingly long.

I agree except I think 100 lines is definitely worth a method, whereas 15 lines is obviously not worthy for the most cases and yet we do that a lot.My principle has always been: “is this part a isolated and intuitive subroutine that I can clearly name and when other people see it they’ll get it at first glance without pausing to think what this does (not to mention reading through the implemention)”. I’m surprised this has not been a common wisdom from many others.

You can write long functions in a bad way, don&#x27;t get me wrong. I&#x27;m just saying the rule that the length itself is an anti-pattern has no inherent validity.

I don&#x27;t agree. If there are side effects happening which may be relevant, the section of code within a long function is executing in a clearly defined state (the stuff above it has happened, the stuff below it won&#x27;t happen until it finishes) while the same code in a separate function could be called from anywhere. Even without side effects, if it&#x27;s called from more than one place, you have to think about all of its callers before you change its semantics, and before you look, you don&#x27;t know if there is more than one caller. Therefore the section of code can be reasoned about with much lower cognitive load. This may be why larger subroutines correlate with lower bug rates, at least in the small number of published empirical studies.The advantage of small subroutines is not that they&#x27;re more logically tractable. They&#x27;re less logically tractable! The advantage is that they are more flexible, because the set of previously defined subroutines forms a language you can use to write new code.Factoring into subroutines is not completely without its advantages for intellectual tractability. You can write tests for a subroutine which give you some assurance of what it does and how it can be broken. And (in the absence of global state, which is a huge caveat) you know that the subroutine only depends on its arguments, while a block in the middle of a long subroutine may have a lot of local variables in scope that it doesn&#x27;t use. And often the caller of the new subroutine is more readable when you can see the code before the call to it and the code after it on the same screen: code written in the language extended with the new subroutine can be higher level.

Because a function clearly defines the scope of the state within it, whereas a section of code within a long function does not. Therefore a function can be reasoned about in isolation, which lowers cognitive load.

Yep, basically “I agree with this statement a lot.” It’s very much an “online Americanism.”

It&#x27;s a call for others to take note of the important or profound message being highlighted. So more than just &quot;I agree&quot;.

In the superlative, yes. It&#x27;s a fairly new phrase, and hardly in my parlance, but it&#x27;s growing on me when I&#x27;m in informal typed chat contexts.

When someone says &quot;this&quot; they are basically pointing at a comment and saying &quot;this is what I think too&quot;.&quot;So much&quot; is applied to intensify that.So, yes, it&#x27;s a strong assertion of agreement with the comment they&#x27;re replying to.

As a non English speaker, what does &quot;so much this&quot; mean?Does it essentially just mean &quot;I agree&quot;?

For me it depends. Sometimes I find value in making a function for a block of work I can give its own name to, because that can make the flow more obvious when looking at what the function does at a high level. But arbitrarily breaking up a function just because is silly and pointless.

A useful trick is to then at least visually structure those 150 lines with comments that separate some blocks of functionality. Keeps the linear flow but makes it still easier to digest.

To paraphrase a recentish comment from jerf, “sometimes you just have a long list of tasks to do”. That stuck with me. Now I’m a bit quicker to realize when I’m in that situation and don’t bother trying to find a natural place to break up the function.

It comes down to the quality of the abstractions. If they are well made and well named, you&#x27;d rather read this:<pre><code> axios.get(&#x27;https:&#x2F;&#x2F;api.example.com&#x27;, {
 headers: { &#x27;Authorization&#x27;: &#x27;Bearer token&#x27; },
 params: { key: &#x27;value&#x27; }
 })
 .then(response =&gt; console.log(response.data))
 .catch(error =&gt; console.error(error));
</code></pre>
than to read the entire implementations of get(), then() and catch() inlined.

This is not my experience. Multiple inheritance within a code base of certain sub-functionalities and states is a perfectly good example of reuse. You do not need to go all the way out to the library level. In fact, it is the abstract bases that really minimize the reusable parts that I find most useful.I&#x27;m not saying you have to use classes to do this, but they certainly get the job done.

Surely this is use case dependent? I’ve worked on projects where modular programming works well and others where not so much.

&gt; The whole point of functions and classes was to make code reusable.I’m amazed that here we are &gt;40 years on from C++, and still this argument is made. Classes never encapsulated a module of reusability, except in toy or academic examples. To try and use them in this way either leads to gigantic “god” classes, or so many tiny classes with scaffolding classes between them that the “communication overhead” dwarfs the actual business logic.Code base after code base proves this again and again. I have never seen a “class” be useful as a component of re-use. So what is? Libraries. A public interface&#x2F;api wrapping a “I don’t care what you did inside”. Bunch of classes, one class, methods? So long as the interface is small and well defined, who cares how it’s structured inside.Modular programming can be done in any paradigm, just think about the api and the internal as separate things. Build some tests at the interface layer, and you’ve got documentation for free too! Re-use happens at the dll or cluster of dll boundaries. Software has a physical aspect to it as well as code.

Indeed and breaking out logic into more global scopes has serious downsides if that logic needs to be modified in the future, if your system still needs to support innovation and improvements, downsides not totally unlike the downsides of using a lot of global variables instead of local ones.Prematurely abstracting and breaking code out into small high level chunks is bad. I try to lay it out from an information theoretic, mathematical perspective here:<a href="https:&#x2F;&#x2F;benoitessiambre.com&#x2F;entropy.html" rel="nofollow">https:&#x2F;&#x2F;benoitessiambre.com&#x2F;entropy.html</a>with some implications for testing:<a href="https:&#x2F;&#x2F;benoitessiambre.com&#x2F;integration.html" rel="nofollow">https:&#x2F;&#x2F;benoitessiambre.com&#x2F;integration.html</a>It all comes down to managing code entropy.

<pre><code> # Can&#x27;t import at the start, because of the need to bootstrap the
 # environment via `get_requires_for_build_*`.
 
</code></pre>
This comment is a great example of what information you lose when you split linear code into small interrelated methods. You lose ordering and dependencies.Sometimes it&#x27;s worth it. Sometimes it isn&#x27;t. In my opinion it&#x27;s almost never worth it to get to the Uncle Bob&#x27;s approved length of methods.10-30 lines is OK. 3 is counterproductive except for a small subset of wrappers, getters etc. Occasionally it&#x27;s good to leave a method that is 300 lines long.If your code always does 9 things in that exact order - it&#x27;s counterproductive to split them artificially into 3 sets of 3 things to meet an arbitrary limit.

This is how I work as well, and the reason I tend to write many small functions rather than few large ones is precisely because it reduces cognitive load. You don&#x27;t have to understand what the canSubmit function does, unless you are interested in knowing what the conditions to submit this form are.Ironically, the author of the post claims it has the opposite effect.

&gt;why the hell would it be &quot;easier to read&quot; if I had to jump up and down the file to 7 different submethods when the function&#x27;s entire flow is always sequential?Because you don&#x27;t jump up and down the file to read it.Each method that you create has a name, and the name is an opportunity to explain the process - naturally, in-line, without comments.I write code like this all the time - e.g. from my current project: <a href="https:&#x2F;&#x2F;github.com&#x2F;zahlman&#x2F;bbbb&#x2F;blob&#x2F;master&#x2F;src&#x2F;bbbb.py">https:&#x2F;&#x2F;github.com&#x2F;zahlman&#x2F;bbbb&#x2F;blob&#x2F;master&#x2F;src&#x2F;bbbb.py</a> . If I wanted to follow the flow of execution, I would be hammering the % key in Vim. But I don&#x27;t do that, because I don&#x27;t need or want to. The flow of the function is already there in the function. It calls out to other functions that encapsulate details that would be a distraction if I want to understand the function. The functions have names that explain their purpose. I put effort into names, and I trust myself and my names. I only look at the code I&#x27;m currently interested in. To look at other parts of the code, I would first need a reason to be interested in it.When you look at yourself in the mirror, and notice your hand, do you feel compelled to examine your hand in detail before you can consider anything about the rest of your reflection? Would you prefer to conceive of that image as a grid of countless points of light? Or do you not find it useful that your mind&#x27;s eye automatically folds what it sees into abstractions like &quot;hand&quot;?35 years into my journey as a programmer, the idea of a 100-line function frightens me (although I have had to face this fear countless times when dealing with others&#x27; code). For me, that&#x27;s half of a reasonable length (though certainly not a hard limit) for the entire file.

There&#x27;s just no way I buy that I could safely make a change in a 100 loc function and know that there won&#x27;t be an impact 30 lines down, where with a few additional function you can define the shape of interactions and know that if that shape&#x2F;interface&#x2F;type is maintained that there won&#x27;t be unexpected interactions. Its a balance though as indirection can also readily hide and obscure interactions or add unnecessary glue code that also takes up mental bandwidth and requires additional testing to confirm.

Mantras like &quot;methods should be shorter than 15 lines of code&quot; or &quot;classes should be small&quot; turned out to be somewhat wrong.So much this.The whole point of functions and classes was to make code reusable. If the entire contents of a 100 line method are only ever used in that method and it&#x27;s not recursive or using continuations or anything else weird, why the hell would it be &quot;easier to read&quot; if I had to jump up and down the file to 7 different submethods when the function&#x27;s entire flow is always sequential?

I thought these things were pretty inferable

That short&#x2F;long toggle in the top-right seems to expand and collapse the article. It defaults to short. Reading this article in its short form I kept wondering if I was missing something relevant (cognitive load++), but with the long form on I kept wondering if some paragraphs were explicitly intended to be superfluous or tangential (cognitive load++) for the sake of that collapsing trick.For an article on cognitive load, using a gimmick which increases it seems ironic.

They all say that, but it&#x27;s true for only 20% of my encounters when you actually watch them code next to others.

hi, tiling window manager and neovim user here.I don&#x27;t think about states much, it&#x27;s all just muscle memory. Like doing a hadouken in street fighter.

Something I noticed is that some vim &#x2F; keyboard only envs are paying a huge cognitive load price by holding various states in their mind and having to expand efforts every time they switching context.Sometimes there is the added burden of an exotic linux distro or a dvorak layout on a specially shaped keyboard.Now, some devs are capable of handling this. But not all do, I&#x27;ve seen many claiming they are more productive with it, but when compared to others, they were less productive.They were slow and tired easily. They had a higher burn out rate. The had too much to pay upfront for their day to day coding task but couldn&#x27;t see that their idealization of their situation was not matching reality.My message here is: if you are in such env be very honest with yourself. Are you good enough that you are among the few that actually benefit from it?

I think it&#x27;s all about the framework, the memory palace you build to keep things organized. A secondary factor is the freedom and solitude to prevent extraneous concerns from interrupting you. The brain is not great at true multitasking (doing two or more things at the same time), but it can juggle.

I commented on this in another thread here.What I read it as is don’t over-index on creating separate layers&#x2F;services if they are already highly dependent on each other. It just adds additional complexity tracing dependencies over the networking stack, databases&#x2F;datastores, etc that the services are now split across.In other words: a monolithic design is acceptable if the services are highly intertwined and dependent.

I think the &#x27;Layered Architecture&#x27; section is all over the place.There are a lot of terms thrown around with pretty loose definitions - in this article and others. I had to look up &quot;layered architecture&quot; to see what other people wrote about it, and it looks like an anti-pattern to me:<pre><code> In a four-layered architecture, the layers are typically divided into:
 Presentation
 Application
 Domain
 Infrastructure

 These layers are arranged in a hierarchical order, where each layer provides services to the layer above it and uses services from the layer below it, and each layer is responsible for handling specific tasks and has limited communication with the other layers. [1]
</code></pre>
It looks like an anti-pattern to be because, as described, each layer depends on the one below it. It looks like how you&#x27;d define the &quot;dependency non-inversion&quot; principle. Domain depends on Infrastructure? A BankBalance is going to depend on MySQL? Even if you put the DB behind an interface, the direction of dependencies is still wrong: BankBalace-&gt;IDatabase.Back to TFA:&gt; In the end, we gave it all up in favour of the good old dependency inversion principle.OK. DIP is terrific.&gt; No port&#x2F;adapter terms to learnThere is a big overlap between ports&#x2F;adapters, hexagonal, and DIP:<pre><code> Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases. [2]
</code></pre>
That is, the Domain (&quot;application&quot;) is at the bottom of the dependency graph, so that the Infrastructure {Programs, Tests, Scripts} can depend upon it.&gt; If you think that such layering will allow you to quickly replace a database or other dependencies, you&#x27;re mistaken.Layering will not help - it will hinder, as I described above. But you should be able to quickly replace any dependency you like, which is what DIP&#x2F;PortsAdapters&#x2F;Hexagonal gives you.&gt; Changing the storage causes lots of problems, and believe us, having some abstractions for the data access layer is the least of your worries. At best, abstractions can save somewhat 10% of your migration time (if any)I iterate on my application code without spinning up a particular database. Same with my unit tests. Well worth it.[1] <a href="https:&#x2F;&#x2F;bitloops.com&#x2F;docs&#x2F;bitloops-language&#x2F;learning&#x2F;software-architecture&#x2F;layered-architecture" rel="nofollow">https:&#x2F;&#x2F;bitloops.com&#x2F;docs&#x2F;bitloops-language&#x2F;learning&#x2F;softwar...</a>
[2] <a href="https:&#x2F;&#x2F;alistair.cockburn.us&#x2F;hexagonal-architecture&#x2F;" rel="nofollow">https:&#x2F;&#x2F;alistair.cockburn.us&#x2F;hexagonal-architecture&#x2F;</a>

If you feel like you are missing key parts of the argument, like I was, it might help to switch the view from &quot;short&quot; to &quot;long&quot; - there&#x27;s a little slider on the right hand side of the screen. This adds in some paragraphs that help the piece flow better. (I&#x27;d never seen a blog post with this feature before.)

I agree. I find this part of the article weird as it has contracting statements:&gt; No port&#x2F;adapter terms to learnand&gt; we gave it all up in favour of the good old dependency inversion principleBoth use interfaces, just in different ways. We use hexagonal (ports and adapters) pattern in my project. If you asked anyone on my team to define hexagonal architecture they&#x27;ll have no idea what you&#x27;re talking about. They just follow the project coding patterns. There&#x27;s no additional complexity.&gt; If you think that such layering will allow you to quickly replace a database or other dependencies, you&#x27;re mistakenI think most people do not stay at companies long enough to see the price of not abstracting away these things. That&#x27;s the next developer&#x27;s problem. The code tends to be tightly coupled to the libraries and frameworks used. Eventually, the projects dependencies have to be upgraded (usually due to security issues) and the migrations are usually incredibly difficult, expensive, and fragile. The product&#x27;s business logic is tightly coupled with the framework and libraries used at the time. Even if the company realizes that framework has no future, they&#x27;re kind of locked into their initial decision made a decade ago. At least, that&#x27;s been my experience.We have two major products at my company. Both started with the same initial framework, but the project I architected that used hexagonal was migrated to a faster and more modern framework within 4 weeks. The other product had a multi-year migration to a newer version of the same framework (and by the time it was completed is already two major versions outdated). Both products are similar in scale and code size.

I agree with vast majority of the post, and it matches my experience. What I&#x27;m not sure I follow is the part about layered architecture, and what is offered as an alternative. The author quickly gets to a _conclusion_ that&gt; So, why pay the price of high cognitive load for such a layered architecture, if it doesn&#x27;t pay off in the future?where one of the examples is&gt; If you think that such layering will allow you to quickly replace a database or other dependencies, you&#x27;re mistaken. Changing the storage causes lots of problems, and believe us, having some abstractions for the data access layer is the least of your worries.but in my experience, it&#x27;s crucial to abstract away — even if the interface is not ideal — external dependencies. The point is not to be able to &quot;replace a database&quot;, but to _own_ the interface that is used by the application. Maybe the author only means _unnecessary layering_, but the way the argument is framed seems like using external dependency APIs throughout the entire app is somehow better.

Also depends on whether it’s obvious why I need a list of odd numbers.

&gt; &quot;Neither of them have type declarations or hints, or give me a clue what will happen if &quot;numbers&quot; doesn&#x27;t contain numbers.&quot;bools in Python are False==0 and True==1, and I&#x27;m now imagining an inexperienced dev believing those things are numbers and has no idea they could be anything else, and is filtering for Trues with the intent of counting them later on, but they messed up the assignment and instead of &#x27;numbers&#x27; always getting a list of bools it sometimes gets a scalar single bool outside a list instead. They want to check for this case, but don&#x27;t understand types or how to check them at all, but they have stumbled on these filter&#x2F;loop which throw when run against a single answer. How useful! Now they are using those lines of code for control flow as a side effect.

This is ridiculous. You can assume that you know what language you are reviewing&#x2F;working in (sorry, I forgot to mention that the example is in Python). I can remember cases when I was not sure what [human] language I thinking in, but I don&#x27;t remember a single case when there was a confusion what programming language I&#x27;m working in (it is not a factor in cognitive load).filter is a builtin name in Python. There is no confusion here in practice. Static checker such as ruff will tell you if you attempt it accidentally. It is the first rule: A001 builtin-variable-shadowing.If you are a noob the second variant may be easier to grasp. The first variant has less moving parts.

Rather depends if we can trust that it&#x27;s Python&#x27;s &quot;filter&quot; or if it&#x27;s another language you&#x27;re making look Pythonic, and we don&#x27;t know who implemented filter&#x2F;2 or how.- The first one might be an in-place filter and mutate &quot;numbers&quot;, the second one definitely isn&#x27;t.- The first one might not be Python&#x27;s filter and might be a shadowed name or a monkeypatched call, the second one definitely isn&#x27;t.- The first one isn&#x27;t clear whether it filters odd numbers in, or filters them out, unless you already know filter&#x2F;2; the second one is clear.- The first one relies on you understanding first-class functions, the second one doesn&#x27;t.- The first one isn&#x27;t clear whether it relies on `numbers` being a list or can work with any sequence, the second one clearly doesn&#x27;t use list indexing or anything like it and works on any sequence that works in a `for` loop.- The first one gives no hint what it will do on an empty input - throw an exception, return an error, or return an empty list. The second one is clear from the patterns of a `for` loop.- The first one has a risk of hiding side-effects behind the call to filter, the second one has no call so can&#x27;t do that.- Neither of them have type declarations or hints, or give me a clue what will happen if &quot;numbers&quot; doesn&#x27;t contain numbers.- The first one isn&#x27;t clear whether it returns a list or a generator, the second one explicitly uses () wrapper syntax to make a generator comprehension.- The first one has a risk of hiding a bad algorithm - like copying &quot;numbers&quot;, doing something &quot;accidentally n^2&quot; - while the second one is definitely once for each &quot;n&quot;.Along the lines of &quot;code can have obviously no bugs, or no obvious bugs&quot; the second one has less room for non-obvious bugs. Although if the reader knows and trusts Python&#x27;s filter then that helps a lot.Biggest risk of bugs is that odd(n) tests if a number is part of the OEIS sequence discovered by mathematician Arthur Odd...

It is not how &quot;cognitive load&quot; is usually understood (as it relates to the working memory, measured by task-involved pupillary response). It involves anything and everything that is not already stored in your long term memory.I remember spending egregiously long time to find a bug that was essentially a typo in some constant. Expressiveness of the language, how many chunks you have to keep in the working memory matters. The chunks can be low&#x2F;high level depending on what you are trying to do at the moment but you can&#x27;t escape looking at the low level details at some point.

The argument isn&#x27;t about these minor syntactic or API differences. It&#x27;s about the structure of the code, in the SICP (<a href="https:&#x2F;&#x2F;en.wikipedia.org&#x2F;wiki&#x2F;Structure_and_Interpretation_of_Computer_Programs" rel="nofollow">https:&#x2F;&#x2F;en.wikipedia.org&#x2F;wiki&#x2F;Structure_and_Interpretation_o...</a>) sense.

What causes more cognitive load:<pre><code> filter(odd, numbers)
</code></pre>
vs.<pre><code> (n for n in numbers if odd(n))
</code></pre>
It depends on the reader too.

Disagree with first example. If that condition is only used once, adding a variable introduces more state to keep track of, that could just be a comment next to the conditional.

Perhaps I&#x27;m confused, but it seems to me that your examples actually support my point. You&#x27;re describing experience-based patterns - seniors over-abstracting vs juniors writing tangled code. Neither case is about intelligence; they&#x27;re about different types of inexperience leading to different design mistakes.

the latter is not better though, it&#x27;s terrible actually, deep nesting is the essence of cognitive load

I find that it comes most from intelligence.  I see plenty of super experienced but not very smart engineers design terrible over engineered systems.  On the other hand, juniors err in the opposite direction with long functions with deep nested branching and repetition.  And the latter is better.  Easier to refactor up in abstraction level than down.

I agree with everything you&#x27;re saying, but these are different issues - not symptoms of excess intellect. Just post-hoc rationalization of poor choices.

I love what you&#x27;re saying. But, I&#x27;ve met a lot of people who have say 10-20 years experience designing applications with unnecessary and sometimes incredible cognitive load. There are serious incentives to NOT write &quot;simple&quot; code, let me share a few of them.Root causes from my perspective look like:
1. Job security type development. Fearful&#x2F;insecure developers make serious puzzle boxes. &quot;Oh yea wait until they fire me and see how much they need me, I&#x27;m the only one who can do this.&quot;2. Working in a vacuum&#x2F;black hole developers. Red flags are phrases like &quot;snark I could have done this&quot; when working together on a feature with them. Yes, that is exactly the point, and I even hope the junior comes in after and can build off of it too.3. Mixing work with play &quot;I read this blog post about category theory and found this great way to conceptualize my code through various abstractions that actually deter from runtime performance but sound really cool when we talk about it at lunch&quot;.4. Clout&#x2F;resume&#x2F;ego chasing &quot;I want to say something smart at stand up, a conference, or at a future job, so other people know they are not on my level and cannot touch my code or achieve my quality.&quot;Some other red flags. They alone maintain their &quot;pet&quot; projects for everything serious until they couldn&#x27;t. Minor problems&#x2F;changes come up, someone else goes in and fixes it. Something serious happens it&#x27;s a stop the world garbage collection for that developer and they are the only one who can fix it disrupting any other operations they were part of.

Yeah it&#x27;s kind of a weird narrative.  Writing complex code is leaps and bounds easier than writing simple code.   Often takes both experience and intelligence to see the correct way.

The &quot;too smart developers&quot; narrative is pandering - poor design stems from inexperience and its accompanying insecurity, not intelligence. Skilled developers intuitively grasp the value of simplicity.

Composition over inheritance is one of the most valuable lessons I learned earlier in my career as a developer. In fact these days, I&#x27;m hard-pressed to think of a case in which I would prefer inheritance as my first choice to model any problem. I&#x27;m sure there probably are some, but it feels too easy to wield irresponsibly and let bad design creep in.At a previous job I had, a fairly important bit of code made use of a number of class hierarchies each five or six layers deep, including the massive code smell&#x2F;design failure of certain layers stubbing out methods on a parent class due to irrelevancy.To make matters worse, at the point of use often only the base&#x2F;abstract types were referenced, so even working out what code was running basically required stepping through in a debugger if you didn&#x27;t want to end up like the meme of Charlie from Always Sunny. And of course, testing was a nightmare because everything happened internally to the classes, so you would end up extending them even further in tests just to stub&#x2F;mock bits you needed to control.

&gt; AdminController extends UserController extends GuestController extends BaseController&gt; Cognitive load in familiar projects -- If you&#x27;ve internalized the mental models of the project into your long-term memory, you won&#x27;t experience a high cognitive load.^ imo using third-party libraries checks both of these boxes because 1) a fresh-to-project developer with general experience may already know the 3rd party lib, and 2) third party libraries compete in the ecosystem and the easiest ones win

Thank you for asking! My phrasing may not have been the most clear.My background is in humanities and health care. I currently work in eldercare. Computers have always been a major interest of mine since an early age, but professionally I have taken another route. I have a general curiosity about systems and theories of different kinds. I do have an education in the basic scientific approach, something I acquired while studying to become a teacher. Soft sciences have often come more easily to me. I lack the benefits of a disciplined study of computer science, something I am sure affects my approach.My use of the word &#x27;emergent&#x27; was inspired by systems theory [0], where the whole is more than the sum of its parts. The parts of a system create emergent behaviors or phenomena. For example: A football team consists of several players, and the strategy of the teamwork is an emergent phenomenon. Similarly, my thought was that when functions are spread out into several modules, they may create unexpected emergent complexity. Without being able to give a concrete example off the top of my head, I think I have struggled with bugs born out of such complexity.My thought was that the &quot;syntactical encapsulation&quot; (the actual code we write) may not serve the &quot;conceptual class&quot; (the idea we have). We may have a good concept, but we distribute its functionality among too many classes.[0] <a href="https:&#x2F;&#x2F;en.wikipedia.org&#x2F;wiki&#x2F;Systems_theory" rel="nofollow">https:&#x2F;&#x2F;en.wikipedia.org&#x2F;wiki&#x2F;Systems_theory</a>

Had to re-read this several times to grasp the meaning..Curious, what is your background and day to day work to be able to express your thinking in these terms?

&gt; &quot;Having too many shallow modules can make it difficult to understand the project. Not only do we have to keep in mind each module responsibilities, but also all their interactions.&quot;Not only does it externalize internal complexity, but it creates emergent complexity beyond what would arise between and within deeper modules.In a sense, shallow modules seem to be like spreading out the functions outside the conceptual class while thinking the syntactical encapsulation itself, rather than the content of the encapsulation, is the crucial factor.

On the layered architecture section:I have seen too many architectures where an engineer took “microservices” too far and broke apart services that almost always rely on each other into separate containers&#x2F;VMs&#x2F;serverless functions.I’m not suggesting people build monolithic applications, but it’s not necessarily a good idea to break every service into its own distinct stack.

The problem with DRY and generic rules around size, etc. really seems to be figuring out the boundaries, and that&#x27;s tough to get right, even for experienced devs, plus very contextual. If you need to open up a dozen files to make a small change you&#x27;re overwhelmed, but then if you need to wade through a big function  or change code in 2 places you&#x27;re just as frustrated.

Same deal with DRY, the principle is obviously correct but people can take it too literally. It&#x27;s so easy to get yourself in a huge mess trying to extract out two or three bits of code that look pretty similar but aren&#x27;t really used in the same context.

I don’t have your experience but I personally think some of this feedback can be warranted.&gt; Can&#x27;t refactor code because it changes too many files and too many lines.This really depends on the change. If you are just doing a mass rename like updating a function signature, fair enough but if you changing a lot of code it’s very hard to review it. Lots of cognitive load on the reviewer who might not have the same understanding of codebase as you.&gt; Can&#x27;t commit large chunks of well tested code that &#x27;Does feature X&#x27;, because... too many files and too many lines.Same as the above, reviewing is hard and more code means people get lazy and bored. Just because the code is tested doesn’t mean it’s correct, just means it passes tests.&gt; Have to split everything down into a long sequence of consecutive pull requests that become a process nightmare in its own rightThis is planning issue, if you correctly size tickets you aren’t going to end up in messy situations as often.&gt; The documentation comments gets nitpicked to death with mostly useless comments about not having periods at the ends of linesHaving correctly written documentation is important. It can live a long time and if you don’t keep an eye on it can becomes a mess. Ideally you should review it before you submitting it to avoid these issues.&gt; End up having to explain every little detail throughout the function as if I&#x27;m trying to produce a lecture, things like `&#x2F;* loop until not valid *&#x2F; while (!valid) {...` seemed to be what they wanted, but to me it made no sense what so ever to even have that commentI definitely agree with this one. Superfluous comments are a waste of time.Obviously this is just my option and you can take things too far but I do think that making code reviewable (by making it small) goes a long way. No one wants to review 1000s lines of code at once. It’s too much to process and people will do a worse job.Happy to hear your thoughts.

That&#x27;s rough. Of course some amount of thoughtfulness towards &quot;smallest reasonable change&quot; is valuable, but if you&#x27;re not shipping then something is wrong.As for the &quot;comments on every detail&quot; thing... I would fight that until I win or have to leave. What a completely asinine practice to leave comments on typical lines of code.

You always need to look at the track record of the team. If they were not producing solid consistent results before you joined them, it&#x27;s a very good indicator that something&#x27;s fishy. All that &quot;they are working on something else that we can&#x27;t tell you&quot; is BS.If they were, and you were the only one treated like that, hiring you was a decision forced upon the team, so they got rid of you in a rather efficient way.

I am trying my best to build in an inordinate amount of upfront linting and automated checks just to avoid such things - and then I still need to do a roadshow, or lots of explanations- but that’s probably good.But the good idea is to say “we all have the same brutal linting standards (including full stops in docs!) - so hopefully the human linger will actually start reading the code for what it is, not what it says”

No wonder why software development used to be expensive if 50 lines of code takes multiples days for several people …

Indeed, cognitive load is not the only thing that matters. Non-cognitive toil is also a problem and often enough it doesn&#x27;t get sufficient attention even when things get really bad.We do need better code review tools though. We also need to approach that process as a mechanism of effectively building good shared understanding about the (new) code, not just &quot;code review&quot;.

This sounds more like a case where you need a “break-the-glass” like procedure where some checks don’t apply. Or the checks should be non blocking anyway.

there is huge incentive for people who don&#x27;t know how to code&#x2F;create&#x2F;do-stuff to slow things down like this b&#x2F;c it allows them many years of runway at the company.they are almost always cloaked in virtue signals.almost every established company you join will already have had this process going for a long time.doing stuff successfully at such a company is dangerous to the hierarchy and incurs an immune response to shut down or ostracize the doing-of-stuff successfully so the only way to survive or climb is to do stuff unsuccessfully (so they look good)

You seem to be describing a company where bureaucracy is a feature not a bug.Been there. Left, live thousands times better.

&gt; The documentation comments gets nitpicked to death with mostly useless comments about not having periods at the ends of lines
&gt; End up having to explain every little detail throughout the functionFor these cases I like to use the ‘suggest an edit’ feature on gitlab&#x2F;github. Can have the change queued up in the comments and batch commit together, and takes almost no additional time&#x2F;effort for the author. I typically add these suggestion comments and give an approve at the same time for small nitpicks, so no slow down in the PR process.

I’m 15 years in and I feel basically the same. I end up making a feature or change, then going back and trying to split it into chunks that are digestible to my colleagues. I’ve got thousands of lines of staged changes that I’m waiting to drip out to people at a digestible pace.I yearn for the early stage startup where every commit is a big change and my colleagues are used to reviewing this, and I can execute at my actual pace.It’s really changed the way I think about software in general, I’ve come around to Rich Hickey’s radically simple language Clojure, because types bloat the refactors I’m doing.I’d love to have more of you where I work, is there some way I can see your work and send some job descriptions and see if you’re interested?

Aye. Sign of the times. You&#x27;re 20+ years in, so I&#x27;m preaching to the choir and old-man-yelling-at-cloud here.Cargo culting + AI are the culprits. Sucks to say, but engineering is going downhill fast. First wave of the shitularity. Architects? Naw, prompt engineers. Barf. Why write good code when a glorified chatbot could do it shittier and faster?Sign of our times. Cardboard cutout code rather than stonemasonry. Shrinkflation of thought.Peep this purified downvote fuel:Everything is bad because everyone is lazy and cargo cults. Web specifically. Full-stop. AI sucks at coding and is making things recursively worse in the long run. LLMs are nothing more than recursive echo chambers of copypasta code that doesn&#x27;t keep up with API flux.A great example of this is the original PHP docs, which so, so many of us copypasta&#x27;d from, leading to an untold amount of SQL injections. Oopsies.Simalarily and hunting for downvotes, React is a templating framework that is useful but does not even meet its original value proposition, which is state management in UI. Hilariously tragic. See: original example of message desync state issue on FB. Unsolved for years by the purported solution.The NoSQL flash is another tragic comedy. Rebuilding the wheel when there is a faster, better wheel already carefully made. Postgres with JSONB.GraphQL is another example of Stuff We Don&#x27;t Need But Use Because People Say It&#x27;s Good. Devs: you don&#x27;t need it. Just write a query.-You mention a hugely important KPI in code. How many files, tools, commands, etc must I touch to do the simplest thing? Did something take me a day when it should have taken 30s? This is rife today, we should all pay attention. Pad left.Look no further than hooks and contexts in React land for an example. Flawed to begin with, simply because &quot;class is a yucky keyword&quot;. I keep seeing this in &quot;fast moving&quot; startups: the diaspora of business logic spread through a codebase, when simplicity and unity is key, which you touch on. Absolute waste of electricity and runway, all thanks to opiniation.Burnt runways abound. Sometimes I can&#x27;t help but think engineering needs a turn it off and then on again moment in safe mode without fads and chatbots.

The process is introducing more room for bugs to somehow creep in. Damn.

I&#x27;ve had a similar experience several times over the years. Even at companies with no working product that ostensibly wanted to &#x27;move fast and break things&#x27;. And I do the same thing; quit and move on. I&#x27;m pretty convinced people like that more-or-less can&#x27;t be reasoned with.My question is .. is this getting more common as time goes on, or do I just feel like it is..

After 20 years of doing this, I’m convinced that required PR reviews aren’t worth the cost.In the thousands of pull requests I’ve merged across many companies, I have never once had a reviewer catch a major bug (a bug that is severe enough that if discovered after hours, would require an oncall engineer to push a hot fix rather than wait for the normal deployment process to fix it).I’ve pushed a few major bugs to production, but I’ve never had a PR reviewer catch one.I’ve had reviewers make excellent suggestions, but it’s almost never anything that really matters. Certainly not worth all the time I’ve spent on the process.That being said, I’m certainly not against collaboration, but I think required PR reviews aren’t the way to do it.

I&#x27;m one of the rare individuals who really tries to review code and leave helpful comments. I&#x27;ve been on the receiving end of really big PRs and can say I understand why you&#x27;re being told to break things up into smaller chunks.Most of the devs who submit large PRs just don&#x27;t have a good grasp of organizing things well enough. I&#x27;ve seen this over and over again and it&#x27;s due to not spending enough time planning out a feature. There will be exceptions to this, but when devs keep doing it over and over, it&#x27;s the reviewer&#x27;s job to reject it and send it back with helpful feedback.I also understand most people don&#x27;t like the friction this can create and so you end you with 80% of PRs being rubber stamped and bugs getting into production because the reviewers just give up on trying to make people better devs.

&gt; mostly useless comments about not having periods at the ends of linesOh my god, this sounds like a nightmare. I definitely would not be able to tolerate this for long.Did you try to get them to change? Were you just not in a senior enough position for anyone to listen?

As a reviewer I&#x27;ve seen numerous examples of PRs that were basically out of sync with the rest of the project, did not solve the problem they were supposed to solve, or added buggy or unmaintainable code.Arguments like &quot;but it works in majority of cases&quot; are a way to delegate fixing issues to somebody else later. Unless noone will be using that code at all, in which case it should not be merged either.

This is the bane of my existence at the moment after ~20 years into my career, and it frustrates me when I run into these situations when trying to get certain people to review pull requests (because I&#x27;m being kind, and adhering to a process, and there is really valuable feedback at times). But on the whole it&#x27;s like being dragged back down to working at a snails pace.- Can&#x27;t refactor code because it changes too many files and too many lines.- Can&#x27;t commit large chunks of well tested code that &#x27;Does feature X&#x27;, because... too many files and too many lines.- Have to split everything down into a long sequence of consecutive pull requests that become a process nightmare in its own right- The documentation comments gets nitpicked to death with mostly useless comments about not having periods at the ends of lines- End up having to explain every little detail throughout the function as if I&#x27;m trying to produce a lecture, things like `&#x2F;* loop until not valid *&#x2F; while (!valid) {...` seemed to be what they wanted, but to me it made no sense what so ever to even have that commentThis can turn a ~50 line function into a 3 day process, a couple of hundred lines into a multi-week process, and a thousand or two line refactor (while retaining full test coverage) into a multi-month process.At one point I just downed tools and quit the company, the absurdity of it all completely drained my motivation, killed progress &amp; flow and lead to features not being shipped.Meanwhile with projects I&#x27;m managing I have a fairly good handle on &#x27;ok this code isnt the best, but it does work, it is fairly well tested, and it will be shipped as the beta&#x27;, so as to not be obstinate.

It&#x27;s the same with writing. The best authors occasionally break the rules of grammar and spelling in order to achieve a specific effect. But you have to learn the rules first, and break them only intentionally rather than accidentally. Otherwise your writing ends up as sloppy crap.(Of course some organizations have coding conventions that are just stupid, but that&#x27;s a separate issue.)

If a function is longer than what I can display on a single screen, it better has to be argumented with very exceptional relevant requirements, which is just as straight forward to judge for anyone with a bit of experience.

Weirdly if you do break everything down into purely functional components it&#x27;s entirely possible to uncompromisingly make every concept a few lines of code at most, and you will end up with some extremely elegant solutions this way.You wouldn&#x27;t be misled at all, only that the path you&#x27;d go down is an entirely different one to what you expected it to be.

&gt; I know these ridiculous statements are from people hardly wrote any code in their livesSome people who actually wrote a decent amount of code in their lives are sharing that opinion, so your comment just sounds like an ad-hominem attack.

I&#x27;ve seen a book promoting the idea that methods should not be longer than 5 lines.Of course now I know these ridiculous statements are from people hardly wrote any code in their lives, but if I&#x27;d read them at 18 I would have been totally misled.

You&#x27;re  confusing this with a software development process problem. It&#x27;s really just good old fashioned psychological abuse.

I like to call these smells, not rules. They&#x27;re an indication that something might be wrong because you&#x27;ve repeated code, or because your method is too long, or because you have too many parameters. But it might also be a false positive because in this instance it was acceptable to repeat code or have a long method or have many parameters.Sometimes food smells because it turned bad, and sometimes it&#x27;s smelly because it&#x27;s cheese.

&gt;It almost always comes from a lead or manager who reads too many business books and then cargo cults those books on to the team.Worse, they behave as though they have profound insights, and put themselves on an intellectually elevated pedestal, which the rest of their ordinary team mortals cannot achieve.

I&#x27;m an experienced developer and I enforce these kinds of rules upon myself without giving it much thought, and I very much prefer the results.

In my experience it usually devs that do that to themselves after reading stuff on the internet and thinking “I want to be a professional and I want to show it to everyone.”Then rules stay and new people just continue with same silly rules instead of thinking if those are really that useful.

There are certainly functions written too cleverly to be apparent how they manage to work at all in a few lines. By my own hand six months ago sometimes. The solution is an unsexy one but always works: write a books worth of comments near that function code that explains absolutely everything and why it was done.

Hard rules are the problem. There is a lot of &quot;it depends.&quot;After over 40 years of programming, I continue to reduce the size of functions and find it easier to write and understand when I return to them. Ten lines are now a personal guideline.However, a linear function with only tiny loops or conditionals can be easily understood when hundreds of lines are long, but not so much with nested conditionals and loops, where there is natural decomposition into functions.I observed that the same guidelines became rules problems when test coverage became popular. They soon became metrics rather than tools to think about code and tests. People became reluctant to add sanity check code for things that could should never happen because it brought down code coverage.

Doing things the right way always introduces a shackle to your ankle. Oh am I to package my functions as discrete packages I call via library name carefully crafted to install into some specific folder structure that I now have to learn and not make mistakes with. Or I can do it “improperly” and just write a function and start using it immediately.Not everything has to be designed like some standardized mass produced part ready to drop into anything made in the last 40 years. And what is crazy is that even things written to that standard aren’t even compatible and might have very specific dependencies themselves.

&gt; Mantras like &quot;methods should be shorter than 15 lines of code&quot; or &quot;classes should be small&quot; turned out to be somewhat wrong.These hard rules may be useful when trying to instill good habits in juniors, but they become counterproductive when you start constraining experienced developers with arbitrary limits.It’s really bad when you join a team that enforces rules like this. It almost always comes from a lead or manager who reads too many business books and then cargo cults those books on to the team.

Every SOLID, Clean Code, DRY and so on are all terrible advice sold by a bunch of people who haven’t worked in software development since before Python was invented. Every one of those principles are continently vague so that people like Uncle Bob can claim that you got it wrong when it doesn’t work for you. Uncle Bob is completely correct though, but maybe the reason you many others got it wrong is because the principles are continently vague. Continently because people like Uncle Bob are consultants who are happy to sell your organisation guidance. I think the biggest nail in the coffin of everything from TDD to Clean Architecture should be that they clearly haven’t worked. It’s been more than 20 years and software is more of a mess than if ever was. If all these “best practices” worked, they would have worked by now.YAGNI is the only principle I’ve seen consistently work. There are no other mantras that work. Abstractions are almost always terrible but even a rule like “if you rewrite it twice” or whatever people come up with aren’t universal. Sometimes you want an abstraction from the beginning, sometimes you never want to abstract. The key is always to keep the cognitive load as low as possible as the author talks about. The same is true for small functions, and I’ve been guilty of this. It’s much worse to have to go through 90 “go to definition” than just read through one long function.Yet we still teach these bad best practices to young developers under the pretence that it works and that everything else is technical debt. Hah, technical debt doesn’t really exist. If you have to go back and replace part of your Python code with C because it’s become a bottle neck that means you’ve made it. 95% of all software (and this number is angry man yelling at clouds) will never need to scale because it’ll never get more than a few thousand users at best. Even if your software blows up chances are you won’t know where the future bottle necks will be so stop trying to solve them before you run into them.

I think Cognitive Load on a developer includes distractions&#x2F;interruptions. Constant slack notifications, taps on the shoulder, meetings, etc. increase cognitive load. It&#x27;s context switching. One only has so much memory and focus, to switch tasks one has additional overhead, thinking and memory&#x2F;storage demands.

Layering (properly) is used to manage dependencies. You isolate interface logic from business logic with data in between. It lets you evolve the architecture. This is a useful abstraction, not just something academic.<a href="https:&#x2F;&#x2F;www.destroyallsoftware.com&#x2F;talks&#x2F;boundaries" rel="nofollow">https:&#x2F;&#x2F;www.destroyallsoftware.com&#x2F;talks&#x2F;boundaries</a>

IMO cognative load is much easier to manage when required (human) memory use is less of a factor. In practical terms, this means maximising the locality of reasoning, i.e., having everything you need in front of you to make a decision. One of the reasons I favour rust is precisely because this factor has been a focus in the design.

I&#x27;m not saying that the conclusions in the article are false. As a programmer, I prefer composition to inheritance, too. I&#x27;m saying that the justifications are presented using a scientific term of art (cognitive load), but the scientific evidence regarding cognitive load isn&#x27;t sufficient to justify these claims.

Congrats on your PhD at Stanford, but some humility has to be part of the scientific process for sure. It looks like a lot of folks called &quot;programmers&quot; agree with the points in the post. If it&#x27;s such a common experience that should tell you something about the state of affairs.It&#x27;s a blog post on the internet. Of course one should take it with a grain of salt. The same applies to any peer-reviewed article on software engineering for example.Just yesterday, I was watching this interview with Adam Frank [0] one of the parts that stood out was his saying why &quot;Why Science Cannot Ignore Human Experience&quot; (I can&#x27;t find the exact snippet, but apparently he has a book with the same title.[0] <a href="https:&#x2F;&#x2F;www.youtube.com&#x2F;watch?v=yhZAXXI83-4" rel="nofollow">https:&#x2F;&#x2F;www.youtube.com&#x2F;watch?v=yhZAXXI83-4</a>

The article is attempting to use a scientific term of art, &quot;cognitive load&quot;, to justify claims about programming. Those claim cannot be justified given the existing evidence about cognitive load. As I explain in my linked response, I nonetheless agree with many of the claims, but they&#x27;re best understood as folk theories than scientific theories.And I don&#x27;t think condescension will make this a productive discussion!

Where was the word “scientific” mentioned in the article? I don’t think you were the target reader they had in mind when the author wrote this. I’ve been programming since 1986, and this article resonates with my experience. More abstractions, layers, and so on requires my brain to have to keep track of more shit which takes away from doing the work that brought me to work on that bit of code (bug fix, feature work, debugging, etc.)We’re very proud of you and the hard work you did to earn your PhD, now please stop trotting it out.

Not knowledgeable enough to weigh in here, I just think it&#x27;s very cool that 1) the authors blog was in public source control and 2) you made a polite github issue with your criticisms and 3) it wasn&#x27;t deleted.

Thanks for sharing your knowledge and please ignore some of the other comments. HN is a place for &quot;intellectual curiosity&quot;, but for some reason it always attracts its fair share of anti-intellectualism. Debating what cognitive load actually is is very relevant to the topic at hand.FWIW, I can&#x27;t speak to the science of it but as a programmer I even disagree with many of the conclusions in the article, such as that advanced language features are bad because they increase mental load.

I did my PhD at Stanford about the cognitive aspects of programming, including studies of cognitive load. This article uses pseudoscience to justify folk theories about programming. I would encourage readers to take everything with a grain of salt, and do not wave this article around as a &quot;scientific&quot; justification for anything.I laid out my objections to the article last year when it first circulated: <a href="https:&#x2F;&#x2F;github.com&#x2F;zakirullin&#x2F;cognitive-load&#x2F;issues&#x2F;22">https:&#x2F;&#x2F;github.com&#x2F;zakirullin&#x2F;cognitive-load&#x2F;issues&#x2F;22</a>

<pre><code> AdminController extends UserController extends GuestController extends BaseController
</code></pre>
That&#x27;s nothing... Java enterprise programmer enters the chat

&gt; Too many small methods, classes or modules
&gt; Method, class and module are interchangeable in this contextClass, method, functions are NOT the only way to manage cognitive load. Other ways work well for thinking developers:Formatting - such as a longer lines and lining up things to highlight identical and different bits.Commenting - What a concept?! using comments to make things more clear.Syntactic sugar, moderate use of DSL features, macros... - Is this sometimes the right way?But yeah, if your tool or style guide or programming language even, imposes doing everything through the object system or functions, then someone clearly knew better. And reduced your cognitive load by taking away your choices &#x2F;s.

It&#x27;s definitely on the senior to prompt the junior appropriately. But when you do, they will.

Junior developers probably won&#x27;t say anything, because they are used to not understanding code, and they are not going to second guess the more-experienced author.

Aye, but the joiners may need prompting as well as getting listened to.In each place where I&#x27;ve seen something wildly wrong, the problem has been clear in the first few weeks — sometimes even in the first few days* — but I always start with the assumption that if I disagree with someone who has been at it for years, they&#x27;ve probably got good reasons for the stuff that surprises me.Unfortunately I&#x27;m not very convincing: when I do finally feel confident enough to raise stuff, quite often they do indeed have reasons… bad reasons that ultimately prove to be fatal or near-fatal flaws to their business plans, but the issues only seldom get fixed once I raise them.* one case where the problem was visible in the interview, but I was too young and naive so I disregarded what I witnessed, and I regretted it.

I second this, but one should also be extremely wary of newcomers feedback and try to understand their nature.Some people are extremely resistant to new ideas, some might be simply lazy, some can&#x27;t be bothered to read documentations, etc.Spotting the real person behind the feedback is crucial and often those people need to be fired fast.I myself tend to be lazy when it comes to learn new stuff&#x2F;patterns, especially when I am in the middle of having to progress a project so my own feedback may be more of a frustration for my inability to progress due to having to understand first a, b, c and d which may take considerable time and pain for something I can do in an old way in few minutes.

&gt; Involve junior developers in architecture reviews. They will help you to identify the mentally demanding areas.This.And also, a mantra of my own: Listen carefully to any newcomer in the team&#x2F;company in first 1-3 weeks, until s&#x2F;he gets accustomed (and&#x2F;or stop paying attention to somewhat uneasy stuff). They will tell you all things that are, if not wrong, at least weird.

&gt; Types of cognitive load - Extrinsic&#x2F;IntrinsicThis neatly mirrors the central ideas presented in Out of the Tar Pit [0], which defines accidental and essential complexity.Reading this paper was probably one of the biggest career unlocks for me. You really can win ~the entire game if you stay focused on the schema and keep in touch with the customer often enough to ensure that it makes sense to them over time.OOTP presents a functional-relational programming approach, but you really just need the relational part to manage the complexity of the domain. Being able to say that one domain type is relevant to another domain type, but only by way of a certain set of attributes (in a 3rd domain type - join table), is an unbelievably powerful tool when used with discipline. This is how you can directly represent messy real world things like circular dependencies. Modern SQL dialects provide recursive CTEs which were intended to query these implied graphs.Over time, my experience has evolved into &quot;let&#x27;s do as much within the RDBMS as we possibly can&quot;. LINQ &amp; friends are certainly nice to have if you need to build a fancy ETL pipeline that interfaces with some non-SQL target, but they&#x27;ll never beat a simple merge statement in brevity or performance if the source &amp; target of the information is ultimately within the same DB scope. I find myself spending more time in the SQL tools (and Excel) than I do in the various code tools.[0] <a href="https:&#x2F;&#x2F;curtclifton.net&#x2F;papers&#x2F;MoseleyMarks06a.pdf" rel="nofollow">https:&#x2F;&#x2F;curtclifton.net&#x2F;papers&#x2F;MoseleyMarks06a.pdf</a>

I prefer this style for languages that have either a GC or scoped resource management (eg RAII).However, I think the single exit point holds merit for C, where an early return can easily and silently cause a resource leak. (Unless you use compiler-specific extensions, or enforce rust-style resource ownership, which is really hard without compiler support.)

I have an issue with complex conditions with or without local variable labels for readability. You really shouldn&#x27;t have them at all.At one time, they used to teach that functions should have one entry-point (this is typically a non-issue but can come up with assembly code) and one exit-point. Instead of a complex condition, I much prefer just early returns ie:<pre><code> &#x2F;&#x2F; what&#x27;s going on 1
 if (condition1 || condition2) {
 return;
 }

 &#x2F;&#x2F; what&#x27;s going on 2
 if (condition3 &amp;&amp; condition4) {
 return;
 }

 &#x2F;&#x2F; what&#x27;s going on 3
 if (condition5) {
 return;
 }

 &#x2F;&#x2F; do the thing
 return;</code></pre>

I think it makes some sense when you are working in a language that provides no mechanisms for automatically calling cleanup functions on exiting a scope (i.e. C). But otherwise, early returns are much clearer in most cases.

I&#x27;ve sometimes seen people attack early returns and I&#x27;ve never understood it. To me they make things so much cleaner that it seems like common sense.

Interesting. I am in agreementBut not one word about comments, and only one about naming.Useful comments go a long way to lessening cognitive loadGood names are mnemonics, not documentationI have worked on code bases with zero comments on the purposes of functions, and names like &quot;next()&quot;And I&#x27;ve worked with programmers who name things like &quot;next_stage_after_numeric_input&quot;

This puts things really well. I’ll add into it that between the first white boarding session and the first working MVP there’ll be plenty of stakeholders who change their mind, find new info, or ask for updates that may break the original plan

Plus to everything said. It&#x27;s an everyday life of &quot;maintainer&quot;, picking the next battle to pick the best way to avoid sinking deeper and defending the story that exactly &quot;this&quot; is the next refactoring project. All that while balancing different factors as you mention to actually believe oneself, because there are countless of paths..

&gt; Oh, and in 6 months the unintuitive and confusing concept needs to be completely changed into - surprise, surprise - a completely different but equally unintuitive and confusing concept.But you have to keep the old way of working exactly the same, and the data can&#x27;t change, but also needs to work in the new version as well. Actually show someone there&#x27;s two modes, and offer to migrate their data to version 2? No way - that&#x27;s confusing! Show different UI in different areas with the same data that behaves differently based on ... undisclosed-to-the-user criteria. That will be far less confusing.

It can be done. Sometimes.I am so proud and happy, when I can make a seemingly complicated change quickly, because the architecture was well designed and everthing neatly seperated.Most of the time though, it is exactly like you described. Or randalls good code comic:<a href="https:&#x2F;&#x2F;xkcd.com&#x2F;844&#x2F;" rel="nofollow">https:&#x2F;&#x2F;xkcd.com&#x2F;844&#x2F;</a>Allmost too painful to be funny, when you know the pain is avoidable in theory.Still, it should not be an excuse to be lazy and just write bad code by default. Developing the habit of making everything as clean, structured and clear as possible allways pays of. Especially if that code, that was supposed to be a quick and dirty throw away code experiment somehow ended up being used and 2 years later you suddenly need to debug it.
(I just experienced that joy)

&gt; Oh, and the original author doesn&#x27;t work here anymore so no one&#x27;s here to explain the original code&#x27;s intent.To be fair, even if I still work there I don&#x27;t know that I&#x27;m going to be of much help 6 months later other than a &quot;oh yeah, I remember that had some weird business requirements&quot;

Sounds like a bunch of excellent excuses why code is not typically well factored.  But that all just seems to make it more evident that the ideal format should be more well-factored.

IMO the fact that code tends to become hard over time in the real world, is even more reason to lower cognitive load. Because cognitive load is related to complexity. Things like inheritance make it far too easy to end up with spaghetti. So if it&#x27;s not providing significant benefit, god damn don&#x27;t do it in the first place (like the article mentions).

&gt; Where just the concepts need to be whiteboarded and explained because they&#x27;re unintuitive and confusing.they&#x27;re intuitive to somebody - just not the software engineer. This simply means there&#x27;s some domain expertise which isn&#x27;t available to the engineer.

I mean really nobody wants an app that is slow, hard to refactor, with confusing business logic etc. Everyone wants good proporties.So then you get into what you’re good at. Maybe you’re good at modeling business logic (even confusing ones!). Maybe you’re good at writing code that is easy to refactor.Maybe you’re good at getting stuff right the first time. Maybe you’re good at quickly fixing issues.You can lean into what you’re good at to get the most bang for your buck. But you probably still have some sort of minimum standards for the whole thing. Just gotta decide what that looks like.

&gt; you also need to write it in a convoluted way because, for various annoying reasons, that&#x27;s what performs best on the computer.That&#x27;s nothing to do with hardware. The various annoying reasons are not set in stone or laws of physics. They are merely the path dependency of decades of prioritizing shipping soon because money.

Oh, and there&#x27;s massive use of aspect-oriented programming, the least local paradigm ever!

&gt;It&#x27;s quite easy to imagine a well factored codebase where all things are neatly separated.If one is always implementing new code bases that they keep well factored, they should count their blessings. I think being informed about cognitive load in code bases is still very important for all the times we aren&#x27;t so blessed. I&#x27;ve inherited applications that use global scope and it is a nightmare to reason though. Where possible I improve it and reduce global scope, but that is not always an option and is only possible after I have reasoned enough about the global scope to feel I can isolate it. As such, letting others know of the costs is helpful to both reduce it from happening and to convince stakeholders of the importance of fixing it after it has happened and accounting for the extra costs it causes until it is fixed.&gt;The messy stuff is where the real world concepts need to be transformed into code.I also agree this can be a messy place, and on a new project, it is messy even when the code is clean because there is effectively a business logic&#x2F;process code base you are inheriting and turning into an application. I think many of the lessons carry over well as I have seen an issue with global scope in business processes that cause many of the same issues as in code bases. When very different business processes end up converging into one before splitting again, there is often extra cognitive load created in trying to combine them. A single instance really isn&#x27;t bad, much like how a single global variable isn&#x27;t bad, but this is an anti-pattern that is used over and over again.One helpful tool is working ones way up to the point of having enough political power and earned enough respect for their designs to have suggestions of refactoring business processes be taken into serious consideration (one also has to have enough business acumen to know when such a suggestion is reasonable).&gt;the original author doesn&#x27;t work here anymore so no one&#x27;s here to explain the original code&#x27;s intent.I fight for comments that tell me why a certain decision is made in the code. The code tells me what it is doing, and domain knowledge will tell most of why it is doing the things expected, but anytime the code deviates from doing what one would normally expect to be done in the domain, telling me why it deviated from expected behavior is very important for when someone is back here reading it 5+ years later when no one is left from the original project. Some will suggest putting it in documentation, but I find that the only documentation with any chance of being maintained or even kept is the documentation built into the code.

In my experience, the more convoluted code is more likely to have performance issues.

Nothing about computers is intuitive. Not even using a mouse.A late-breaking change is a business advantage—-learn how to roll with them.

&gt; A function with well-constrained inputs and outputs is easy to reason about.It&#x27;s quite easy to imagine a well factored codebase where all things are neatly separated. If you&#x27;ve written something a thousand times, like user authentication, then you can plan out exactly how you want to separate everything. But user authentication isn&#x27;t where things get messy.The messy stuff is where the real world concepts need to be transformed into code. Where just the concepts need to be whiteboarded and explained because they&#x27;re unintuitive and confusing. Then these unintuitive and confusing concepts need to somehow described to the computer.Oh, and it needs to be fast. So not only do you need to model an unintuitive and confusing concept - you also need to write it in a convoluted way because, for various annoying reasons, that&#x27;s what performs best on the computer.Oh, and in 6 months the unintuitive and confusing concept needs to be completely changed into - surprise, surprise - a completely different but equally unintuitive and confusing concept.Oh, and you can&#x27;t rewrite everything because there isn&#x27;t enough time or budget to do that. You have to minimally change the current uintuitive and confusing thing so that it works like the new unintuitive and confusing thing is supposed to work.Oh, and the original author doesn&#x27;t work here anymore so no one&#x27;s here to explain the original code&#x27;s intent.

In theory, you could design a parallel set of software engineering best practices which emphasize long-term memory of the codebase over short-term ability to leaf through and understand it. I guess that would be &quot;reasoning nonlocally&quot; in a useful sense.In practice I think the only time this would be seen as a potentially good thing by most devs is if it was happening in heavily optimized code.

&gt; The main benefit of Liskov&#x27;s substitution principle is ensure developers don&#x27;t need to dig into each and every concrete implementation to be able to reason locally about the code.Yeah, but doesn&#x27;t help in this context (enable local reasoning) if the objects passed around have too much magic or are mutated all over the place. The enterprise OOP from 2010s was a clusterfuck full of unexpected side effects.

Encapsulation is the good part of object-oriented programming for precisely this reason, and most serious software development relies heavily on encapsulation. What&#x27;s bad about OOP is inheritance.Microservices (in the sense of small services) are interesting because they are good at providing independent failure domains, but add the complexity of network calls to what would otherwise be a simple function call. I think the correct size of service is the largest you can get away with that fits into your available hardware and doesn&#x27;t compromise on resilience. Within a service, use things like encapsulation.

Out of curiosity I sometimes rewrite things as spaghetti (if functions are short and aren&#x27;t called frequently) or using globals (if multiple functions have to many params) it usually doesn&#x27;t look better and when it does it usually doesn&#x27;t stay that way for very long. In the very few remaining cases I&#x27;m quite happy with it. It does help me think about what is going on.

&gt; In fact, is there any software engineering principle that isn&#x27;t pushing for limiting complexity and allowing developers to reason locally?Both DRY and SOLID lead to codebases that can be worse in this respect.DRY and SRP limit what will be done in a single method or class, meaning that both the logic will eventually be strewn across the codebase, as well as any changes to that will need to take all of the pieces using the extracted logic into account. Sometimes it makes sense to have something like common services, helper and utility classes, but those can be in direct opposition to local reasoning for any non-trivial logic.Same for polymorphism and inheritance in general, where you suddenly have to consider a whole class structure (and any logic that might be buried in there) vs the immediate bits of code that you’re working with.Those might be considered decent enough practices to at least consider, but in practice they will lead to a lot of jumping around the codebase, same for any levels of abstraction (resource&#x2F;controller, service, mappers, Dto&#x2F;repository, …) and design patterns.

&gt; I&#x27;ve been thinking about the notion of &quot;reasoning locally&quot; recently. Enabling local reasoning is the only way to scale software development past some number of lines or complexity. When reasoning locally, one only needs to understand a small subset, hundreds of lines, to safely make changes in programs comprising millions.That was supposedly the main trait of object-oriented programming. Personally that was how it was taught to me: the whole point of encapsulation and information hiding is to ensure developers can &quot;reason locally&quot;, and thus be able to develop more complex projects by containing complexity to specific units of execution.Half of SOLID principles also push for that. The main benefit of Liskov&#x27;s substitution principle is ensure developers don&#x27;t need to dig into each and every concrete implementation to be able to reason locally about the code.On top of that, there are a multitude of principles and rules of thumb that also enforce that trait. For example, declaring variables right before they are used the first time. Don&#x27;t Repeat Yourself to avoid parsing multiple implementations of the same routine. Write Everything Twice to avoid premature abstractions and tightly coupling units of execution that are actually completely independent, etc etc etc.Heck, even modularity, layered software architectures, and even microservices are used to allow developers to reason locally.In fact, is there any software engineering principle that isn&#x27;t pushing for limiting complexity and allowing developers to reason locally?

100% agree and this not only concerns readability. The concept of &quot;locality&quot; turns out to be a fairly universal concept, which applies to human processes just as much as technical ones. Side-effects are the root of all evil.You don&#x27;t see a waiter taking orders from 1 person on a table, but rather go to a table and get orders from everybody sitting there.And as for large methods, I find that they can be broken into smaller once just fine as long as you keep them side-effect free. Give them a clear name, a clear return value and now you have a good model for the underlying problem you are solving. Looking up the actual definition is just looking at implementation details.

I&#x27;ve seen functions called getValue() that were actually creating files on disk and writing stuff.Also, even if the function actually does what advertised, I&#x27;ve seen functions that go 4-5 levels deep where the outer functions are just abstracting optional parameters. So to avoid exposing 3 or 4 parameters, tens of functions are created instead.I think you do have a point but ideas get abused a lot.

I&#x27;ve been thinking about the notion of &quot;reasoning locally&quot; recently. Enabling local reasoning is the only way to scale software development past some number of lines or complexity. When reasoning locally, one only needs to understand a small subset, hundreds of lines, to safely make changes in programs comprising millions.I find types helps massively with this. A function with well-constrained inputs and outputs is easy to reason about. One does not have to look at other code to do it. However, programs that leverage types effectively are sometimes construed as having high cognitive load, when it in fact they have low load. For example a type like `Option&lt;HashSet&lt;UserId&gt;&gt;` carries a lot of information(has low load): we might not have a set of user ids, but if we do they are unique.The discourse around small functions and the clean code guidelines is fascinating. The complaint is usually, as in this post, that having to go read all the small functions adds cognitive load and makes reading the code harder. Proponents of small functions argue that you don&#x27;t have to read more than the signature and name of a function to understand what it does; it&#x27;s obvious what a function called last that takes a list and returns an optional value does. If someone feels compelled to read every function either the functions are poor abstractions or the reader has trust issues, which may be warranted. Of course, all abstractions are leaky, but perhaps some initial trust in `last` is warranted.

Cognitive load is what matters