Cognitive load is what matters

https://github.com/zakirullin/cognitive-load

by nromiun • 11 months ago

1582 522 11 months ago

delichon• 11 months ago

The AI version of this is the degradation when the context window gets too large. The fix is the same too, summarize and reset.

ashwinsundar• 11 months ago

AI does not have a cognitive load problem in remotely the same way people do. People can chunk and re-chunk info based on their skill and experience, but even the best AI just knows one thing - token length

ijk• 11 months ago

Given the way attention works, it seems to me that AI has an even more concrete instantiation of cognitive load.

marginalia_nu10• 11 months ago

I think it's pretty tiresome that "smart authors" are blamed for writing complex code. Smart authors generally write simpler code. It's much harder to write simple code than complex for reasons that boil down to entropy -- there are simply many more ways to write complex code than simple code, and finding one of the simple expressions of program logic requires both smarts and a modicum of experience.

If you try to do it algorithmically, you arguably won't find a simple expression. It's often glossed over how readability in one axis can drive complexities along another axis, especially when composing code into bite-size readable chunks the actual logic easily gets smeared across many (sometimes dozens) of different functions, making it very hard to figure out what it actually does, even though all the functions check all the boxes for readability, having a single responsibility, etc.

E.g. is userAuthorized(request) is true but why is it true? Well because usernamePresent(request) is true and passwordCorrect(user) is true, both of which also decompose into multiple functions and conditions. It's often a smaller cognitive load to just have all that logic in one place, even if it's not the local optimum of readability it may be the global one because needing to constantly skip between methods or modules to figure out what is happening is also incredibly taxing.

incognito124• 11 months ago

You reminded me of a rule of thumb that says: Keep the complexities in data structures and simplicity in algorithms

hibikir• 11 months ago

I have seen subscription systems built following that rule of thumb. It collapses pretty well, as the data structure then becomes impossible to engage with unless you are an expert, and the callers are never experts.

Things make more sense when the data structure lives in a world where most, if not all illegal atates become unrepresentable. But given that we often end un building APIs in representations with really weak type systems, doing that becomes impossible.

peacebeard• 11 months ago

It’s really easy to generalize. Some smart people write simple, maintainable code. Some smart people find it fun to over-complicate. Neither is useful as a generalization in my opinion.

baobabKoodaa2• 11 months ago

When an article like this uses the term "smart people", I'm always a bit confused if they mean actually smart people, or not-that-smart-people-who-think-highly-of-themselves. Because there's a lot more people in the latter category, and in my view they are the ones building unnecessary complexity into codebases.

To clarify, when I say "not-that-smart-people", I don't mean "stupid people". You need to be beyond some basic level of intelligence in order to have the capability to overcomplicate a codebase. For lack of a better metric, consider IQ. If your IQ is below 80, you are not going to work day-to-day overcomplicating a codebase. You need to be slightly above average intelligence (not stupid, but also "not-that-smart") to find yourself in that position.

marginalia_nu10• 11 months ago

It takes intelligence to see where to make a change though.

If you make a change at the wrong place, you add more complexity than if you put the change in the right place. You often see the same thing with junior developers, in that case due to a limited mental model of the code. You give them a task that from a senior developer would result in a 2 line diff and they come back changing 45 lines.

aDyslecticCrow6• 11 months ago

I like to call that a leaky abstraction. The author used "UNIX I/O" as a great example. It perfectly hides the complexity and abstraction is such a way that the programmer never needs to know the internals. It has sealed all the juicy complexity in a watertight container that the user of the abstraction never needs to peak inside of.

The auth example may not be. You may need to do validatePassword(user) for passwordCorrect(user) to be true, which then forces you to open up a hole in the abstraction that is userAuthorized(request) and peak inside. userAuthorized() has leaked out its logic, it has failed as an abstraction. Its a box with 3 walls and no roof that blocks visibility to important logic rather than hides away the complexity.

munchlax• 11 months ago

If you're refering to fopen and friends, that's leaky too. Fopen alone has an append mode which was meant for tapes. And binary mode that was probably useful some day, but hasn't been since idk when. Fsync has its own set of trouble.

Read the fine print.

st3fan2• 11 months ago

"Smart authors generally write simpler code"

I don't like to generalize.

You are lucky then. I've definitely worked with super smart engineers who chose incredibly complicated solutions over more simpler and pragmatic solutions. As a result the code was generally hard to maintain and specially difficult to understand.

It is a real thing. And it generally happens with "the smart ones" because people who don't know how to make things complicated generally stick with simpler solutions. In my experience.

weiliddat6• 11 months ago

It's much harder to write simple code than complex for reasons that boil down to entropy -- there are simply many more ways to write complex code than simple code, and finding one of the simple expressions of program logic requires both smarts and a modicum of experience.

Also effort, there are smart people who couldn't be bothered to reduce extraneous load for other people, because they already took the effort to understand it, but they don't have the theory-of-mind to understand that it's not easy for others, or can't be bothered to do so.

I have only made this letter longer because I have not had the time to make it shorter. - Blaise Pascal

Good rule of thumb I find is, did the new change make it harder or easier to reason about the change / topic?

If we go back to the concept of cognitive load, it's fine cognitive load goes up if the solution is necessarily complex. It's the extraneous bit that we should work to minimize, reduce if possible.

zahlman4• 11 months ago

Smart authors generally write simpler code. It's much harder to write simple code than complex for reasons that boil down to entropy -- there are simply many more ways to write complex code than simple code, and finding one of the simple expressions of program logic requires both smarts and a modicum of experience.

The people writing the complex code generally seem to think they're smart.

That was me, once. And I was smart, but I was also applying my smarts very, very poorly.

Buttons8406• 11 months ago

I'm probably one of the "smart developers" with quirks. I try to build abstractions.

I'm both bothered and intrigued by the industry returning to, what I call, "pile-of-if-statements architecture". It's really easy to think it's simple, and it's really easy to think you understand, and it's really easy to close your assigned Jira tickets; so I understand why people like it.

People get assigned a task, they look around and find a few places they think are related, then add some if-statements to the pile. Then they test; if the tests fail they add a few more if-statements. Eventually they send it to QA; if QA finds a problem, another quick if-statement will solve the problem. It's released to production, and it works for a high enough percentage of cases that the failure cases don't come to your attention. There's approximately 0% chance the code is actually correct. You just add if-statements until you asymptotically approach correctness. If you accidentally leak the personal data of millions of people, you wont be held responsible, and the cognitive load is always low.

But the thing is... I'm not sure there's a better alternative.

You can create a fancy abstraction and use a fancy architecture, but I'm not sure this actually increases the odds of the code being correct.

Especially in corporate environments--you cannot build a beautiful abstraction in most corporate environments because the owners of the business logic do not treat the business logic with enough care.

"A single order ships to a single address, keep it simple, build it, oh actually, a salesman promised a big customer, so now we need to make it so a single order can ship to multiple addresses"--you've heard something like this before, haven't you?

You can't build careful bug-free abstractions in corporate environments.

So, is pile-of-if-statements the best we can do for business software?

vasco• 11 months ago

So, is pile-of-if-statements the best we can do for business software?

I'm not sure if that's anywhere in the rating of quality of business software. Things that matter:

1. How fast can I or someone else change it next time to fulfill the next requirements?

2. How often does it fail?

3. How much money does the code save or generate by existing.

Good architecture can affect 1 and 2 in some circumstances but not every time and most likely not forever at the rate people are starting to produce LLM garbage code. At some point we'll just compile English directly into bytecode and so architecture will matter even less. And obviously #3 matters by far the most.

It's obviously a shame for whoever appreciates the actual art / craft of building software, but that isn't really a thing that matters in business software anyway, at least for the people paying our salaries (or to the users of the software).

whoamii• 11 months ago

Plenty of architecture to be found in well written text.

Swizec2• 11 months ago

So, is pile-of-if-statements the best we can do for business software?

You’ll enjoy the Big Ball of Mud paper[1].

Real world systems are prone to decay. You first of all start with a big ball of mud because you’re building a system before you know what you want. Then as parts of the system grow up, you improve the design. Then things change again and the beautiful abstraction breaks down.

Production software is always changing. That’s the beauty of it. Your job is to support this with a mix of domain modeling, good enough abstraction, and constructive destruction. Like a city that grows from a village.

[1] https://laputan.org/mud/mud.html

[2] my recap (but the paper is very approachable, if long) https://swizec.com/blog/big-ball-of-mud-the-worlds-most-popu...

conradkay• 11 months ago

First link is broken

https://s3.amazonaws.com/systemsandpapers/papers/bigballofmu...

citizenpaul2• 11 months ago

I'm not sure the author or most people that write these types of academic theory papers ever really see actual ball-of-mud-spaghetti code in real world scenarios.

I think anyone that thinks mudball is OK because business is messy has never seen true mudball code.

I've had to walk out of potential work because after looking at what they had I simply had to tell them I cannot help you, you need a team and probably at minimum a year to make any meaningful progress. That is what mudballs leads to. What this paper describes is competent work that is pushed too quickly for cleaning rough edges but has some sort of structure.

I've seen mudballs that required 6-12 months just to do discovery of all the pieces and parts. Hundreds of different version of things no central source control, different deployment techniques depending on the person that coded it even within the same project.

hmottestad• 11 months ago

Been playing with Codex CLI the past week and it really loves to create a fix for a bug by adding a special case for just that bug in the code. It couldn't see the patterns unless I pointed them out and asked it to create new abstractions.

It would just keep adding what it called "heuristics", which were just if statements that tested for a specific condition that arose during the bug. I could write 10 tests for a specific type of bug, and it would happily fix all of them. When I add another one test with the same kind of bug it obviously fails, because the fix that Codex came up with was a bunch of if statements that matched the first 10 tests.

Buttons8406• 11 months ago

It's clear that these AIs are approaching human level intelligence. (:

Thank you for giving a perfect example of what I was describing.

The thing is, you actually can make the software work this way, you just have to add enough if-statements to handle all cases--or rather, enough cases that the manager is happy.

xyzzy123• 11 months ago

Also they hedge a lot, will try doing things one way, have a catch / error handler and then try a completely different way - only one of them can right but it just doesn't care. Have to lean hard to get it to check which paths are actually used and delete the others.

I am convinced this behaviour and the one you described are due to optimising for swe benchmarks that reward 1-shotting fixes without regard to quality. Writing code like this makes complete sense in that context.

marginalia_nu10• 11 months ago

I honestly think that's pretty close to optimal for a lot of places. With business software it's often not desirable to have large sweeping changes. You may need some small change to a rule or condition, but usually you want things to stay exactly the way they are.

The model of having a circle of ancient greybeards in charge of carefully updating the sacred code to align with the business requirements, while it seems bizarre bordering on something out of WH40K, actually works pretty well and has worked pretty well everywhere I've encountered it.

Attempts to refactor or replace these systems with something more modern has universally been an expensive disaster.

Buttons8406• 11 months ago

It does work for awhile, until one day:

Project Manager: "Can we ship an order to multiple addresses?"

Grey Beard: "No. We'd have to change thousands of random if-statements spread throughout the code."

Project Manager: "How long do you think that would take?"

Grey Beard: "2 years or more."

Project Manager: "Okay, we will break you down--err, I mean, we'll need to break the task down. I'll schedule long meetings until you relent and commit to a shorter time estimate."

Grey Beard eventually relents and gives a shorter time estimate for the project, and then leaves the company for another job that pays more half-way through the project.

api• 11 months ago

A pile of if statements is a direct model of business deal making, which is literally a pile of if statements.

Sales contracts with weird conditions and odd packaging and contingencies? Pile of if statements.

The other great model for business logic is a spreadsheet, which is well modeled by SQL which is a superset of spreadsheet functionality.

So piles of if’s and SQL. Yeah.

Elegant functional or OOP models are usually too rigid unless they are scaffolding to make piles of conditions and relational queries easier to run.

dsego7• 11 months ago

You usually don't want your code logic to stray from the mental or domain model of business stakeholders. Usually when my code makes assumptions to unify things or make elegant hierarchies, I find myself in a very bad place when stakeholders later make decisions that flip everything and make all my assumptions in the code base structure fall apart.

marcosdumay2• 11 months ago

So piles of if’s and SQL.

One would imagine by now we would have some incredibly readable logical language to use with the SQL on that context...

But instead we have people complaining that SQL is too foreign and insisting we beat it down until it becomes OOP.

To be fair, creating that language is really hard. But then, everybody seems to be focusing on destroying things more, not on constructing a good ecosystem.

AnimalMuppet• 11 months ago

But even with OOP... Virtual functions take over the pile of ifs, and so the ifs move to where you instantiate the class that has the virtual functions. (There is some improvement, though - one class can have many virtual functions, so you can replace all the ifs that ask the same question with one if that creates a class with all the right virtual functions. It gets messier if your class has to be virtual against more than one question.)

whstl2• 11 months ago

I believe you can build great abstractions in this kind of software, but if you want them to survive you gotta keep them any of that away from anything involving the business logic itself. You can only do this on product-like things: authn/authz, audit logs, abstractions over the database (CQRS, event sourcing), content/translation management, messaging infrastructure, real infrastructure. As soon as you allow anything from the business itself to affect or dictate those abstractions, you get shit again.

You're right that the business logic is gonna be messy, and that's because nobody really cares, and they can offload the responsibility to developers, or anyone punching it in.

On the other hand, separating "good code" and "bad code" can have horrible outcomes too.

One "solution" I saw in a fintech I worked at, was putting the logic in the hands of business people itself, in the form of a decision engine.

Basically it forced the business itself to maintain its own ball of mud. It was impossible to test, impossible to understand and even impossible simulate. Eventually software operators were hired, basically junior-level developers using a graphical interface for writing the code.

It was rewritten a couple times, always with the same outcome of everything getting messy after two or three years.

vjerancrnjak2• 11 months ago

There are many ways code can get simpler even with ifs.

If you find yourself sprinkling ifs everywhere, try to lift them up, they’ll congregate at the same place eventually, so all of your variability is implemented and documented at a single place, no need to abstract anything.

It’s very useful to model your inputs and outputs precisely. Postpone figuring out unified data types as long as possible and make your programming language nice to use with that decision.

Hierarchies of classes, patterns etc are a last resort for when you’re actually sure you know what’s going on.

I’d go further and say you don’t need functions or files as long as your programming is easy to manage. The only reason why you’d need separate files is if your vcs is crippled or if you’re very sure that these datetime handlers need to be reused everywhere consistently.

Modern fullstack programming is filled with models, middleware, Controllers , views , … as if anyone needs all of that separation up front.

soulofmischief• 11 months ago

These abstractions become a toolset for creating a program that naturally evolves as new goals and constraints are introduced. It also allows other engineers to understand your code at a high level without reading it from top to bottom.

If your code ever has the possibility of changing, your early wins by having no abstraction are quickly paid for, with interest, as you immediately find yourself refactoring to a higher abstraction in order to reason about higher-order concepts.

In this case, the abstraction is the simplicity, for the same reason that when I submit this comment, I don't have to include a dictionary or a definition of every single word I use. There is a reason that experienced programmers reach for abstractions from the beginning, experience has taught them the benefits of doing so.

The mark of an expert is knowing the appropriate level of abstraction for each task, and when to apply specific abstractions. This is also why abstractions can sometimes feel clumsy and indirect to less experienced engineers.

ajzbzizkloll• 11 months ago

Most business logic is “last mile” software. Built on top of beautiful abstractions that came not from an abstract idea of what’s correct but from painful clashes with reality that eventually provided enough clarity to build a good abstraction.

Sometimes last mile software turns into these abstractions but often not.

I’ve worked with very smart devs that try to build these abstractions too early, and once they encounter reality you just have a more confusing version of if statement soup.

atomicnumber3• 11 months ago

"the owners of the business logic do not treat the business logic with enough care."

Certainly, there are such people who simply don't care.

However I would also say that corporations categorically create an environment where you are unable to care - consider how short software engineer tenures are! Any even somewhat stable business will likely have had 3+ generations of owner by the time you get to them. Owner 1 is the guy who wrote 80% of the code in the early days, fast and loose, and got the company to make payroll. Owner 2 was the lead of a team set up to own that service plus 8 others. Owner 3 was a lead of a sub-team that split off from that team and owns that service plus 1 other related service.

Each of these people will have different styles - owner 1 hated polymorphism and everything is component-based, owner 2 wrapped all existing logic into a state machine, owner 3 realized both were leaky abstractions and difficult to work with, so they tried to bring some semblance of a sustainable path forward to the system, but were busy with feature work. And owner 3 did not get any Handoff from person 2 because person 2 ragequit the second enough of their equity vested. And now there's you. You started about 9 months ago and know some of the jargon and where some bodies are buried. You're accountable for some amount of business impact, and generally can't just go rewrite stuff. You also have 6 other people on call for this service with you who have varying levels of familiarity with the current code. You have 2.25 years left. Good luck.

Meanwhile I've seen codebases owned by the same 2 people for over 10 years. It's night and day.

eastbound• 11 months ago

consider how short software engineer tenures are!

Employees aren’t fired. They leave for a 10% increase. Employees are the ones who seek always more in a short-termist way.

Buttons8406• 11 months ago

What you say is true, but I meant the product owners are the one who don't fully weigh the cost of their decisions.

I once tried to explain to a product owner that we should be careful to document what assumptions are being made in the code, and make sure the company was okay committing to those assumptions. Things like "a single order ships to a single address" are early assumptions that can get baked into the system and can be really hard to change later, so the company should take care and make sure the assumptions the programmers are baking into the system are assumptions the company is willing to commit to.

Anyway, I tried to explain all this to the product owner, and their response was "don't assume anything". Brillant decisions like that are why they earned the big bucks.

ttz4• 11 months ago

I was recently having a conversation with some coworkers about this.

IMO a lot of (software) engineering wisdom and best practices fails in the face of business requirements and logic. In hard engineering you can push back a lot harder because it's more permanent and lives are more often on the line, but with software, it's harder to do so.

I truly believe the constraints of fast moving business and inane, non sensical requests for short term gains (to keep your product going) make it nearly impossible to do proper software engineering, and actually require these if-else nests to work properly. So much so that I think we should distinguish between software engineering and product engineering.

andix5• 11 months ago

a lot of (software) engineering wisdom and best practices fails in the face of business requirements

They fail on reality. A lot of those "best" practices assume, that someone understands the problem and knows what needs to be built. But that's never true. Building software is always an evolutionary process, it needs to change until it's right.

Try to build an side project, that doesn't accept any external requirements, just your ideas. You will see that even your own ideas and requirements shift over time, a year (or two) later your original assumptions won't be correct anymore.

sky2224• 11 months ago

This is how I feel as well. What's even worse is that it seems like the academics doing research in the area of software engineering don't really have up to date experience that's practical.

Add to the fact that they're the professor of many software engineering courses and you start to see why so many new grads follow SOLID so dogmatically, which leads to codebases quickly decaying.

markus_zhang• 11 months ago

I kinda think only system programming is programming.

djtango2• 11 months ago

IMO you touch on the real heart of the issue at the end - the real world and business is messy and really _is_ just a pile of if statements.

When the problem itself is technical or can be generalised then abstractions can eliminate the need for 1000s of if-statement developers but if the domain itself is messy and poorly specified then the only ways abstractions (and tooling) can help is to bake in flexibility, because contradiction might be a feature not a bug...

dehrmann• 11 months ago

In most assembly languages, the instructions are essentially load and store, arithmetic operations, and branch and jump. Almost everything is abstractions around how to handle branching and memory.

figassis• 11 months ago

Abstractions are ok, SomethingFactories are stupid. If your code is more abstractions than actual logic and you need logic to manage the abstractions (eg. FactoryFactories, 2+ inheritance levels), you should rethink your strategy.

mdaniel5• 11 months ago

I had previously thought SomethingFactory was abstracting away the logic for the "new" keyword, but for people who dislike inversion of control frameworks

I'm firmly in the "DI||GTFO" camp, so I don't meant to advocate for the Factory pattern but saying that only abstractions that you like are ok starts to generate PR email threads

DarkNova62• 11 months ago

Perhaps expressing intend and describing the underlying domain carries more value than pure “abstraction”.

DarkNova62• 11 months ago

I'm not surprised to be downvoted, it truly speaks for the state of quality in the industry or lack thereof.

oh_my_goodness2• 11 months ago

You can't depend on the business people to understand the business logic clearly enough to explain it to the implementers. That will never happen. They may understand it themselves, but they're not coders and they can't write requirements for code.

Instead, at least one implementer needs to get hands dirty on what the application space really is. Very dirty. So dirty that they actually start to really know and care about what the users actually experience every day.

Or, more realistically for most companies, we insist on separate silos, "business logic" comes to mean "stupid stuff we don't really care about", and we screw around with if statements. (Or, whatever, we get hip to monads and screw around with those. That's way cooler.)

helge9210• 11 months ago

You can carefully pick an order of features to build in a way, that every new feature will invalidate an abstraction correctly implementing all the previous features.

kaffekaka• 11 months ago

Definitely true.

I don't think it is malice or incompetence, but this happens too often to feel good.

energy123• 11 months ago

Better when those if statements are before any loops

HumblyTossed2• 11 months ago

There are two things I hate more than anything else when coding - if statements and abstraction. If statements are bug magnets. Abstraction is a mental drain. My coding stile is to balance those two things in a way that makes the code as easy to read and extend as possible without relying on either too much and only just enough.

gnramires• 11 months ago

I am not a super experienced coder or anything. But I like thinking about it[1].

The way I've been thinking about it is about organization. Organize code like we should organize our house. If you have a collection of pens, I guess you shouldn't leave them scattered everywhere and in your closet, and with your cutlery, and in the bathroom :) You should set up somewhere to keep your pens, and other utensils in a kind of neat way. You don't need to spend months setting up a super-pen-organizer that has a specially sculpted nook for your $0.50 pen that you might lose or break next week. But you make it neat enough, according to a number of factors like how likely it is to last, how stable is your setup, how frequently it is used, and so on. Organizing has several advantages: it makes it easier to find pens, shows you a breath of options quickly, keeps other places in your house tidier and so less cognitively messy as well. And it has downsides, like you need to devote a lot of time and effort, you might lose flexibility if you're too strict like maybe you've been labeling stuff in the kitchen, or doing sketches in your living room, and you need a few pens there.

I don't like the point of view that messiness (and say cognitive load) is always bad. Messiness has real advantages sometimes! It gives you freedom to be more flexible and dynamic. I think children know this when living in a strict "super-tidy" parent house :) (they'd barely get the chance to play if everything needs to be perfectly organized all the time)

I believe in real life almost every solution and problem is strongly multifactorial. It's dangerous to think a single factor, say 'cognitive load', 'don't repeat yourself', 'lesser lines of code', and so on is going to be the single important factor you should consider. Projects have time constraints, cost, need for performance; expressing programs, the study of algorithms and abstractions itself is a very rich field. But those single factors help us improve a little on one significant facet of your craft if you're mindful about it.

Another factor I think is very important as well (and maybe underestimated) is beauty. Beauty for me has two senses: one in an intuitive sense that things are 'just right' (which capture a lot of things implicitly). A second and important one I think is that working and programming, when possible, should be nice, why not. The experience of coding should be fun, feel good in various ways, etc. when possible (obviously this competes with other demands...). When I make procedural art projects, I try to make the code at least a little artistic as well as the result, I think it contributes to the result as well.

[1] a few small projects, procedural art -- and perhaps a game coming soon :)

sfn422• 11 months ago

"A single order ships to a single address, keep it simple, build it, oh actually, a salesman promised a big customer, so now we need to make it so a single order can ship to multiple addresses"--you've heard something like this before, haven't you?

I don't see the problem. Okay, so we need to support multiple addresses for orders. We can add a relationship table between the Orders and ShippingAddresses tables, fix the parts of the API that need it so that it still works for all existing code like before using the updated data model, then publish a v2 of the api with updated endpoints that support creating orders with multiple addresses, adding shipping addresses, whatever you need.

Now whoever is dependent on your system can update their software to use the v2 endpoints when they're ready for it. If you've been foolish enough to let other applications connect to your DB directly then those guys are going to have a bad time, might want to fix that problem first if those apps are critical. Or you could try to coordinate the fix across all of them and deploy them together with the db update.

The problems occur when people don't do things properly, we have solutions for these problems. It's just that people love taking shortcuts and that leads to a terrible system full of workarounds rather than abstractions. Abstractions are malleable, you can change them to suit your needs. Use the abstractions that work for you, change them if they don't work any more. Design the code in such a way that changing them isn't a gargantuan task.

RaftPeople3• 11 months ago

I don't see the problem. Okay, so we need to support multiple addresses for orders. We can add a relationship table between the Orders and ShippingAddresses tables

Which items ship to each of those locations and in which quantities?

What is the status of each of those sub-orders in the fulfillment process?

Should the orders actually ship to those addresses or should the cartons just be packed and marked for those locations for cross-docking and the shipments should be split across some number of regional DC's based on proximity to the final address?

Many things need to be updated in the DB schema+code. And if you think this isn't a very good example, it's a real life example of orders for large retailers.

andix5• 11 months ago

I'm also into building abstractions, but I always try to leave "escape hatches" in place. I try to build my abstractions out of reusable components, that can also be used independently.

If the abstraction doesn't fit a new problem, it should be easy to reassemble the components in a different way, or use an existing abstraction and replace some components with something that fits this one problem.

The developers shouldn't be forced to use the abstractions, they should voluntarily use them because it makes it easier for them.

jsrcout• 11 months ago

it should be easy to reassemble the components in a different way

An underappreciated value. I call this composability and it is one of my primary software development goals.

ajuc3• 11 months ago

I like to make truth tables for understanding piles of ifs. Like there's 5 ifs with 5 different conditions - so I make 5 columns and 32 rows, and enumerate all the possible combinations of these 5 ifs and write what happens for each. And then what should happen.

Of course, the disadvantage is the exponential growth. 20 ifs means a million cases (usually less because the conditions aren't independent, but still).

Then I have a flat list of all possible cases, and I can reconstruct a minimal if tree if I really want to (or just keep it as a list of cases - much easier to understand that way, even if less efficient).

cma2• 11 months ago

Often you can check validity one time before everything else. 5 bools might only actually be valid in 7 possible combinations instead of 32. Convert in one place to a 7 element enum and handle with exhaustive switch statements everywhere else can sometimes be a lot cleaner.

Making invalid data unrepresentable simplifies so much code. It's not always possible but it is way underused. You can do some of it with object encapsulation too, but simple enums with exhaustive switch statements enforced by the compiler (so if it changes you have to go handle the new case everywhere) is often the better option.

BenkaiDebussy2• 11 months ago

I think one issue you can run into with clever abstractions is that it can be harder to fix/change them if something is wrong with their fundamental assumptions (or those assumptions change later). Something like this happened at my work a while back, where if I had written the code it would have probably just involved a few really long/ugly functions (but only required changing a few lines in and after the SQL query to fix), but instead the logic was so deeply intertwined with the code structure that there wasn't any simple way to fix it without straight-up rewriting the code (it was written in a functional way with a bunch of functions taking other functions as arguments and giving functions as output, which also made debugging really tough).

It also depends how big the consequences to failure/bugs are. Sometimes bugs just aren't a huge deal, so it's a worthwhile trade-off to make development easier in change for potentially increasing the chance of them appearing.

rendaw• 11 months ago

There is an alternative: take the parts that _aren't_ in if statements (the actual common code) and make them into shared functions. Then split up the rest into multiple functions that call the shared functions, one for each independent condition, so that they don't have if statements.

These individual functions are easier to reason about since they have specific use cases, you don't have to remember which combinations of conditions happen together while reading the code, they simplify control flow (i.e. you don't have to hack around carrying data from one if block to the next), and it uses no "abstraction" (interfaces) just simple functions.

It's obviously a balance, you'll still have some if statements, but getting rid of mutually exclusive conditions is basically a guaranteed improvement.

james-bcn• 11 months ago

Some of this reminds me of the recommendations on one of the great programming books, Code Complete: https://en.wikipedia.org/wiki/Code_Complete

chrisweekly• 11 months ago

Brilliant essay. Bookmarked for future reference.

dsego7• 11 months ago

I would also recommend A Philosophy of Software Design if you haven't read it, a very short and brilliant read with a similar approach.

There is also a discussion between the author of Clean Code and APOSD:

https://github.com/johnousterhout/aposd-vs-clean-code

bob1029• 11 months ago

At some point, you just need to go with the flow. Worrying about the metacognitive consequences of your work and trying to actively manage this with technological policy will turn into a death spiral. You should always try to take advantage of the momentum in the things around you. Our profession has a reputation for going out of its way to do things like push for a rewrite of a company's codebase after having seen the legacy for 20 minutes. This isn't even a chesterson's fence conversation. This is crude, impulsive behavior that makes any kind of productive business infeasible.

Also, many developers are suffering from severe cognitive load that is incurred by technology and tooling tribalism. Every day on HN I see complaints about things like 5 RPS scrapers crippling my web app, error handling, et. al., and all I can think about is how smooth my experience is from my particular ivory tower. We've solved (i.e., completely and permanently) 95% of the problems HN complains about decades ago and you can find a nearly perfect vertical of these solutions with 2-3 vendors right now. Your ten man startup not using Microsoft or Oracle or IBM isn't going to make a single fucking difference to these companies. The only thing you win is a whole universe of new problems that you have to solve from scratch again.

noen• 11 months ago

This article reminds me of my early days at Microsoft. I spent 8 years in the Developer Division (DevDiv).

Microsoft had three personas for software engineers that were eventually retired for a much more complex persona framework called people in context (the irony in relation to this article isn’t lost on me).

But those original personas still stick with me and have been incredibly valuable in my career to understand and work effectively with other engineers.

Mort - the pragmatic engineer who cares most about the business outcome. If a “pile of if statements” gets the job done quickly and meets the requirements - Mort became a pejorative term at Microsoft unfortunately. VB developers were often Morts, Access developers were often Morts.

Elvis - the rockstar engineer who cares most about doing something new and exciting. Being the first to use the latest framework or technology. Getting visibility and accolades for innovation. The code might be a little unstable - but move fast and break things right? Elvis also cares a lot about the perceived brilliance of their code - 4 layers of abstraction? That must take a genius to understand and Elvis understands it because they wrote it, now everyone will know they are a genius. For many engineers at Microsoft (especially early in career) the assumption was (and still is largely) that Elvis gets promoted because Elvis gets visibility and is always innovating.

Einstein - the engineer who cares about the algorithm. Einstein wants to write the most performant, the most elegant, the most technically correct code possible. Einstein cares more if they are writing “pythonic” code than if the output actually solves the business problem. Einstein will refactor 200 lines of code to add a single new conditional to keep the codebase consistent. Einsteins love love love functional languages.

None of these personas represent a real engineer - every engineer is a mix, and a human with complex motivations and perspectives - but I can usually pin one of these 3 as the primary within a few days of PRs and a single design review.

DonHopkins• 11 months ago

Is Microsoft so Balkanized that they have a Developer Division, Developer Multiplication, Developer Addition, and Developer Subtraction (where you get transferred to before they fire you)?

Waterluvian3• 11 months ago

The larger a corporation gets, the more npm packages you have to first install before accomplishing any meaningful work.

azhenley• 11 months ago

I had a lot of fun in DevDiv!

darkstarsys2• 11 months ago

Clearly they were missing Amanda, the engineer who's had to review others' terrible code (and her own) for 20 years, and has learned the hard way to keep it simple. She knows she's writing code mostly for people to read, not computers. Give me a small team of Amandas any day.

darkstarsys2• 11 months ago

And as a manager/CTO, the way to do this is to give the devs time to think about what they're doing, and reward implementation clarity (though it's its own reward for Amandas).

jadbox• 11 months ago

Mort, Elvis, Einstein, Amanda does seem to fit well with my experience. While people are a mix, generally I think its fair that there is a primary focus/mode that fits on career goals.

- Mort wants to climb the business ladder.

- Elvis wants earned social status.

- Einstein wants legacy with unique contributions.

- Amanda just wants group cohesion and minimizing future unpredictability.

makeitdouble5• 11 months ago

What difference do you see from a Mort ?

If there is no inherent complexity, a Mort will come up with the simplest solution. If it's a complex problem needing trade-offs the Mort will come up with the fastest and most business centric solution.

Or would you see that Amanda refactoring a whole system to keep it simple above all whatever the deadlines and stakes ?

AllegedAlec2• 11 months ago

You clearly missed the entire message of the entire "three kinds of developers" sort of shit if you think that a fourth type that's perfect is what's missing from it.

rawgabbit• 11 months ago

They were also missing Steve Jobs. Having had the displeasure to work with Microsoft tools and code for most of my career. Microsoft never in my experience just plain works. I had to fight Microsoft every step of the way to get things to "work". And when it does it invariably breaks in the next major software release.

socalgal2• 11 months ago

Mort: Someone who lacks sense of life, looks dumbfounded, and has only a limited ability to learn and understand. (urban slang)

Elvis: A famous rock star

Enstein: A famous physicist

Amanda: ???

Mort, Elvis, Enstein are referencing things I've heard of before. What is Amanda referencing? is there some famous person named Amanda? Is it slang I'm unaware of?

latexr• 11 months ago

Amanda

Am I missing a reference? If not, may I suggest “Ada”?

https://en.wikipedia.org/wiki/Ada_Lovelace

Or even better, “Grace”. Seems to fit your description better.

https://en.wikipedia.org/wiki/Grace_Hopper

https://www.youtube.com/watch?v=gYqF6-h9Cvg

1123581321• 11 months ago

Amanda is just the light side of Mort, Elvis or Einstein, since keeping things simple and reviewable can mean staying business-oriented, using the right technology or using an existing tool with deep knowledge.

We would all like our coworkers to never make bad decisions. :)

bravetraveler• 11 months ago

Animal Farm, but with a twist

Disposal8433• 11 months ago

three personas for software engineers

The kind of psycho-bullshit that we should stay away from, and wouldn't happen if we respected each other. Coming from Microsoft is not surprising though.

mdaniel5• 11 months ago

For my frame of reference, do you think the Myers-Briggs Type Indicator are psycho-bullshit, too? Because I had characterized personas as a very similar "of course it's a generalization" and OP even said themselves "every engineer is a mix" but if you're coming from stance that bucketing people is disrespectful, then your perspective on MBTI would help me digest your stance

lgessler• 11 months ago

Novels are fictional too. So long as they're not taken too literally, archetypes can be helpful mental prompts.

AllegedAlec2• 11 months ago

Stereotyping people is good.

fragmede3• 11 months ago

Okay, it's psycho bullshit. How would you organize and sort people instead?

Waterluvian3• 11 months ago

Yeah… it’s like picking three points in an n-dimensional matrix. It is sufficient for creating an illusion of being scientific about it.

tempodox• 11 months ago

Indeed. And besides that, all three are really bad parodies. Mort is the only one where the product actually works, because for him that’s an explicit goal. With the other two, a working product is mere coincidence.

s1mplicissimus• 11 months ago

Exactly the expectation value for "analysis of types of developers done by people who really don't care about people"

"so, there's 3 boxes. no more, no less. why? i have a gut feeling. axis? on a case by case basis. am i willing to put my money where my mouth is? heallnaw!"

freshtake• 11 months ago

The best engineers are all three, and can turn up or down these tendencies depending on what's required for the project, business, or personal goals. These should not be fixed in proportion over time, as they are each useful in different circumstances.

I spent time at Microsoft as well, and one of the things I noticed was folks who spent time in different disciplines (e.g. dev, test, pgm) seemed to be especially great at tailoring these qualities to their needs. If you're working on optimizing a compiler, you probably need a bit more Einstein and Mort than Elvis. If you're working on a game engine you may need a different combination.

The quantities of each (or whether these are the correct archetypes) is certainly debatable, but understanding that you need all of them in different proportions over time is important, IMHO.

purplezooey• 11 months ago

Perhaps best modeled as a waveform that starts before morning coffee. Each engineer has a vector of spectral magnitudes.

roblh• 11 months ago

That’s super interesting. What was the ideal ratio, back then. Is it still the same now? Or I guess maybe it depends on the specific role and could be different in each. What exactly do you find valuable about thinking in these terms?

rapind2• 11 months ago

Mort is the pragmatist, Einstein is the perfectionist, and Elvis is... let's be honest, Elvis is basically cancer to a project. I guess maybe a small dose of Elvis can help motivate?

I see the ideal as a combination of Mort and Einstein that want to keep it simple enough that it can be delivered (less abstraction, distilled requirements) while ensuring the code is sufficiently correct (not necessarily "elegant" mind you) that maintenance and support won't be a total nightmare.

IMO, seek out Morts and give them long term ownership of the project so they get a little Einstein-y when they realize they need to support that "pile of if statements".

As an aside, I'm finding coding agents to be a bit too much Mort at times (YOLO), when I'd prefer they were more Einstein. I'd rather be the Mort myself to keep it on track.

chickenbuckcar• 11 months ago

Unfortunately for a fast growing industry (think AI, LLM), Mort + Elvis will be much more success then any combination with Einstein. The speed to adapt a new technology into a specific domain outweight your ability to scale for long term (think the oracle vs sybase in server)

KronisLV2• 11 months ago

Elvis is basically cancer to a project. I guess maybe a small dose of Elvis can help motivate?

Sometimes teams are quite stuck in their ways because they don’t have the capacity or desire to explore anything new.

For example, an Elvis would probably introduce containers which would eliminate a class of dependency and runtime environment related issues, alongside allowing CI to become easier and simpler, even though previously using SCP and Jenkins and deploying things into Tomcat mostly worked. Suddenly even the front end components can be containers, as can be testing and development databases, everyone can easily have the correct version locally and so on.

An unchecked Elvis will eventually introduce Kubernetes in the small shop to possibly messy results, though.

dahart2• 11 months ago

Your comment made me think Mort represents efficiency, Einstein represents quality, and Elvis represents risk. The ideal combination is difficult, and it changes over time. If anyone knew what the ideal combination was, companies would never fail. Risk can get something started, and lack of it can eventually kill software. In fact, I would argue the vast majority of software we’ve seen so far dies an eventual death due in part to its inability to take risk and change and adapt - it might be not enough Elvis in the long term. Too much risk can kill something before it takes off and can undermine the ability to ship and to ship quality. Generally speaking my gut instinct was to (perhaps like you) align with and defend Morts; the business objective is the only thing that matters and pays the bills, and there is certainly a class of Morts that doesn’t write spaghetti code, and cares about quality and tries new things, but prioritizes work toward the customer and not code wonkery. Anyway… this is too probably abstract to be very useful and I made it worse and more abstract, but it’s fun to hypothesize!

james_marks• 11 months ago

This is a helpful framing, thank you.

Something was bugging me after an interview with a potential hire, and now I can articulate that they were too much Einstein and not enough Mort for the role.

HumblyTossed2• 11 months ago

I lean towards Mort for most things, Einstein for the key things and freaking NEVER Elvis.

jama2117• 11 months ago

Mort is the only one who does their job from the perspective of the business owner.

cgarvis• 11 months ago

Reminds me of the three tribes of software programmers. https://josephg.com/blog/3-tribes/amp/

Mort == maker Elvis ==? hacker Einstein == poet

_dain_• 11 months ago

mort = paladin

elvis = thief

einstein = mage

VagabundoP• 11 months ago

Amanda=Cleric

jama2117• 11 months ago

Who’s the bard? I feel like I’m more of a bard

SteveJS• 11 months ago

Personas are a great tool. IMO - By the time you arrived these had transformed into bad shorthand. (I say this having been in Devdiv through those years.)

Elvis is not a persona - it is an inside baseball argument to management. It suffered a form of Goodhart’s law … it is a useful tool so people phrase their arguments in that form to win a biz fight and then the tool degrades.

Alan Cooper, who created VB advocated personas. When used well they are great.

The most important insight is your own PoV may be flawed. The way a scientist provides value via software is different than how a firmware developer provides value.

https://www.amazon.com/Inmates-Are-Running-Asylum/dp/0672316...

whiteboardr• 11 months ago

If personas in this context resonate with you, I highly recommend - even if only remotely related - to read Rich Gold’s The Plenitude.

https://mitpress.mit.edu/9780262543798/the-plenitude/

jama2117• 11 months ago

I think this is somewhat dangerous, it can lead you to categorise people unfairly and permanently. Also, in my experience this has a critical flaw - the managers love morts in my experience, not Elvises. They don’t care about the technical details, so “fastest and fits the business outcome the most” is ideal.

Also the actual solution is proper team leadership/management. If you have morts, make sure that code quality requirements are a PART of the requirements their code must pass, and they’ll instead deliver decent work slightly slower. Got an elvis? Give more boundaries. Got Einsteins? Redefine the subtasks so they can’t refactor everything and give deadlines both in terms of time but also pragmatism.

Either way, I don’t love this approach, as it removes the complexity from the human condition, complexity which is most important to keep in mind.

zmmmmm2• 11 months ago

I agree with you and one of the most important ways is that it bakes in an assumption that people cant grow, learn and change.

Life is all about learning, adapting and changing. Great leaders see the potential growth in people and are up for having hard conversations about how they can improve.

Even if people do have these personality traits as life long attributes, that doesn't define them or prevent them from learning aspects of the others over time.

augusto-moura• 11 months ago

Can you share what was the new framework? At least some of the details, it sound interesting what was the new understand

TZubiri3• 11 months ago

I'd love one of those old facebook quizzes like "take this quizz to figure out which friends character you are", but for figuring out whether you are a Mort, an Elvis or an Einstein

Buttons8406• 11 months ago

It's been said: "Document the why, not the what."

I have a hard time separating the why and the what so I document both.

The biggest offender of "documenting the what" is:

    x = 4  // assign 4 to x

Yeah, don't do that. Don't mix a lot of comments into the code. It makes it ugly to read, and the context switching between code and comments is hard.

Instead do something like:

    // I'm going to do
    // a thing. The code
    // does the thing.
    // We need to do the
    // thing, because the
    // business needs a
    // widget and stuff.
    
    setup();
    t = setupThing();
    t.useThing(42);
    t.theWidget(need=true);
    t.alsoOtherStuff();
    etc();
    etc();

Keep the code and comments separate, but stating the what is better than no comments at all, and it does help reduce cognitive load.

marginalia_nu10• 11 months ago

I generally don't mind documenting both when it's merited. Sometimes you need to clarify the why, occasionally you need to clarify the what.

I think comments in general are underrated. You don't need to annotate every line like a freshman programming assignment, but on the other hand most supposed self-documenting code just isn't.

mastermage2• 11 months ago

sometimes you do some wack magic in just one line of code, sometimes thats necessary for performance or because what you are trying todo is inherently wack magic. Example the fast inverse square from quake. Insane magic and if you just document does inverse square approximately people would freak out. So sometimes when wack magic is used explain the wack magic (as concise as reasonable)

mastermage2• 11 months ago

I am trying to shift more to this style of commenting. Because I am not a programmer by education. I am a physicist and most physicists are like I want comments in my code so do it like this.. and then you as a student do what you need to for a good grade.

dsego7• 11 months ago

x = 4 // assign 4 to x

Ah, the chat gpt style of comments.

Instead do something like:

The only negative is that there is a chance the comment becomes stale and not in sync with the code. Other coders should be careful to update the comment if they touch the code.

Buttons8406• 11 months ago

If the what becomes stale, you can tell. If the why becomes stale (and it can become stale), you'll never know, unless the what is also included.

Waterluvian3• 11 months ago

The challenge I have these days is deciding what belongs in code and what goes into design documentation and technical manuals.

I generally find that comments in code should explain why the code is doing non-obvious things. “This gets memoized because it’s actually important to maintain referential identity for reason X.”

jijijijij2• 11 months ago

The problem is, a year later the obvious things are not obvious anymore :D

ivanjermakov2• 11 months ago

Such comments are never maintained. Implementation will change 5 times this year and the comment will get stale and confusing.

At my current projects we drop all code comments except for some really tricky logic and very high level docs.

jmpeax• 11 months ago

It makes it ugly to read, and the context switching between code and comments is hard.

That's a symptom of bad syntax highlighting, fix it and you're good to go.

makeitdouble5• 11 months ago

Lowering the cognitive load by assigning temporary variables requires more thought and skill than credited here.

In particular these variables need to be extremely well named, otherwise people reading the code will still need to remember what exactly is abstracted if the wording doesn't exactly fit their vision. E.g.

isSecure = condition4 && !condition5

More often than not the real proper name would be "shouldBeSecureBecauseWeAlsoCheckedCondition3Before"

To a point, avoiding the abstraction and putting a comment instead can have better readability. The author's "smart" code could as well be

  ```
  if (val > someConstant // is valid
      && (condition2 || condition3) // is allowed
      && (condition4 && !condition5) // is secure 
  ) {
      ...
  }
  ```

cowlby• 11 months ago

One quirk of AI agents is I've moved to `isValid = val > someConstant` over comments because Cursor (I guess Claude by extension) frequently removes and re-writes comments. Or `isValid = checkForValidity(val, someConstant)` if the condition check grows significantly.

claytongulick• 11 months ago

I try to structure functions and validations like this in a early-return list at the top of a function.

    if(val <= someconstant)
        return; //not valid

    if(!(condition2 || condition3))
        return; //not allowed

    ...

The author mentions this technique as well.

I find it particularly useful in controller API functions because it makes the code a lot more auditable (any time I see the same set of conditions repeating a lot, I consider whether they are a good candidate for middleware).

I try to explain this to newer developers and they just don't get it, or give me eyerolls.

Maybe sending them this article will help.

SoftTalker• 11 months ago

They can all be right. I agree assigning variables doesn't help much more than good comments. But worth doing if they are needed more than once in the same scope. But do we need "is valid", "is allowed", and "is secure" more than once in differnt scopes? They should probably functions then. Do we always need all three considered together? Then they should be a single function. Are there ever places where condition2 or condition 3 are not allowed? More complexity.

Even simple examples like this get complicated in the real world.

lxe• 11 months ago

Introducing intermediate variables is what I call "indirection". You're adding another step to someone reading the code.

Let's take a recipe:

   Ingredients:
   large bowl
   2 eggs
   200 grams sugar
   500 grams flour
   1/2 tsp soda

   Steps:

   Crack the eggs into a bowl. Add sugar and whisk. Sift the flower. Add the soda.

When following the instruction, you have to always refer back to the ingredients list and search for the quantity, which massively burdens you with "cognitive load". However, if you inline things:

   Crack 2 eggs into a large bowl. Add 200g sugar and whisk. Sift 500g of flower. Add 1/2 tsp soda.

Much easier to follow!

bathtub365• 11 months ago

When making a recipe you usually need to buy some or all of the ingredients. You also want to collect them all together beforehand since it makes things go a lot more smoothly. If they didn’t list them separately it would be easier to miss one.

mdaniel5• 11 months ago

This probably isn't entirely what you meant, but people who do this code smell drive me starkraving mad

  shipToAddress(getShippingAddress(getStreet()),calculateShipping(getShippingAddress(getStreet())))

because as soon as one needs to update the mechanism for getting the shipping address, congratulations, you're updating it everywhere -- or not, nothing matters in this timeline

aDyslecticCrow6• 11 months ago

your example makes me question how much you bake.

The instructions are simple to remember, the ingredient quantities are not. Once i have read the recipe, i have a clear idea what i need to do. But i may need to look up the quantities. Looking for those in a block of text is a waste of time and error prone. Having a recipe formatted like the 2nd example is only useful for a someone inexperienced with baking.

Its also difficult to buy or bring out the ingredients if they're hidden in text. Or know if i can bake something based on what i have or not.

If you've baked an really old recipe from a book, you may find instructions like "Mix the ingredients, put in a pan, bake until brown on high heat", with a list of quantities and not even a picture to know what it is you're baking. An experienced baker will know the right order and tools, and how their oven behaves, so it's not written out at all.

If i look for recipes online, seeing the instructions written like you have makes me reluctant to trust the author, and also makes me annoyed when trying to follow or plan out the process.

pessimizer4• 11 months ago

Redundancy like that makes people like me feel that we missed something, and ruins forward progress. If you started "Crack 1 egg into the bowl." I'd move through it at light speed. When you say "Crack 2 eggs..." I think, "did I miss some ingredients, aren't there only two eggs?" and I rescan the entire ingredient list.

Then, still unsure, I go back and read the end of the sentence. "...into a large bowl."

Another large bowl? Wasn't there only one bowl? Was there another small bowl? Were the other eggs supposed to be in the small bowl? Is there another recipe listed separately where I'm supposed to crack the other egg (that might exist) into a small bowl? A single egg would only need a small bowl. Yes, there's probably another part of the recipe that is a sauce or filling or something that needs you to crack one egg into a small bowl. Let me reread everything on this webpage until I find something referred to that might be a necessary part of finishing this recipe, find the instructions to make that, then come back to this. Also, I have to reevaluate whether I even have enough eggs and bowls to make this recipe. I've read the entire page again, and I can't find what I'm missing. Maybe I'll google another, similar recipe, and they'll be a sauce or side that is mandatory for this dish that everybody already knows about but me, and it will be obvious. Ok, this is something similar, and it's served with some sort of a lemon sauce? I don't think I like lemon sauces. I'm not going to make this, I'm not even sure if I can. I hate trying to find recipes on the internet.

1dom2• 11 months ago

This article makes me feel weird.

I think I'm not smart enough for it. I can't really take anything new away from it, mainly just a message of "we're smart people, and trust us when we say smart things are bad. All the smart sounding stuff you learned about how to program from smart sounding people like us? Lol, that's all wrong now."

Okay, I get the cognitive load is bad, so what's the solution?

"Just do simple dumb stuff, duh." Oh, right... Useful.

The problem is never just the code, or the architecture, or the business, or the cognitive load. It's the mismatch of those things against the people expected to work with them.

Walk into a team full of not-simple engineers, and tell them all what they've been doing is wrong, and they need to just write simple code, some of them will fail, some will walk out, and you'll be no closer to a solution.

I wish I knew of the tech world before 20 years ago, where technical roles were long and stable enough for teams to build their own understanding of a suitable level of complexity. Without that, churn means we all have to aim for the lowest common denominator.

bheadmaster• 11 months ago

Okay, I get the cognitive load is bad, so what's the solution?

Modularity.

Each component in your system should be a (relatively) simple composition of other (smaller) components, in such a way that each component can be understood as a black box, and is interchangable with any other implementation or the same thing.

1dom2• 11 months ago

From the article:

All too often, we end up creating lots of shallow modules, following some vague "a module should be responsible for one, and only one, thing" principle.

This is what I'm talking about: this writing is too smart for me, because I can't take any simple answers from it like "modularity" without feeling another part of the article contradicts it with other smart sounding ways of saying don't listen to smart stuff.

jsd1982• 11 months ago

I think cognitive load has a lot more to do with the paradigm that the code is written in than any particular type of author's contribution to the code. For instance, the object-oriented paradigm by design increases cognitive load by encouraging breaking up otherwise straightforward logic into multiple interfaces, classes, and methods.

MiscCompFacts• 11 months ago

This essay was shared 8 months ago and had significant discussion.

https://news.ycombinator.com/item?id=42489645 (721 comments)

PeterWhittaker2• 11 months ago

The most important user of my temporary variables, à la "isValid" or "isSecure" is older/later me.

I could be adding a new feature six months later, or debugging a customer reported issue a week later. Especially in the latter case, where the pressure is greater and available time more constrained, I love that earlier/younger me was thoughtful enough to take the extra time to make things clear.

That this might help others is lagniappe.

zahlman4• 11 months ago

A lagniappe (/ˈlænjæp/ LAN-yap, /lænˈjæp/ lan-YAP) is "a small gift given to a customer by a merchant at the time of a purchase" (such as a 13th doughnut on purchase of a dozen), or more broadly, "something given or obtained gratuitously or by way of good measure."[2] It can be used more generally as meaning any extra or unexpected benefit.[3]
The word entered English from the Louisiana French adapting a Quechua word brought in to New Orleans by the Spanish Creoles.

... I see.

PeterWhittaker2• 11 months ago

Quite a lovely word. Learned it from Steinem writing a foreword for a Doonesbury collection in which she excoriated Buckley for his use of the term to describe the fourth panel, the main punchline often having come in the third, in his foreword for a previous collection.

edtechdev• 11 months ago

Cognitive load isn't a valid or useful concept: https://edtechdev.wordpress.com/2009/11/16/cognitive-load-th... https://www.tandfonline.com/doi/full/10.1080/00131857.2024.2...

There are separate contexts involved here: the coder, the compiler, the runtime, a person trying to understand the code (context of this article), etc. What's better for one context may not be better for another, and programming languages favor certain contexts over others.

In this case, since programming languages primarily favor making things easier for the compiler and have barely improved their design and usability in 50 years, both coders and readers should employ third party tools to assist them. AI can help the reader understand the code and the coder generate clearer documentation and labels, on top of using linters, test driven development, literate documentation practices, etc.

aDyslecticCrow6• 11 months ago

The linked articles seem to primarily criticize three things about connotative load theory;

- Difficult to measure and therefore a hard or impossible to empirically study. (a bad scientific theory)

- Its application to education and learning theory which where a lot of other techniques are more proven.

- The idea that it's a primary mechanism of human learning, which has had a-lot of research showing otherwise.

Though those points seem valid, this article does not concern itself deeply with this concept. The word "mental strain" or "limited short term memory" could have been inserted in place of "cognitive load", and the points raised would be valid. In effect the article argues we should minimize the amount of things that need to be taken into consideration at any given point when reading (or writing) code. This claim is quite reasonable irrespective of the scientific bases of CTL which it takes its wording from.

So i don't think your criticism is entirely relevant to this article, but raising it does help inform others about issues with the used wording if they happen to want to learn more.

reikonomusha• 11 months ago

I think the criticism is relevant because TFA isn't the first to exercise the term "cognitive load" in the context of computing. It's a term thrown around quite often, so we should cross reference its alleged meaning to literature.

I myself find it to be a term that's effectively used as a thought-terminating cliche, sometimes as a way to defend a critic's preferred coding style and organization.

noiv• 11 months ago

I spend a few decades in the industry and in even more teams. I think, the quality of code strongly correlates with the team's ability to articulate its members cognitive load and skills. In some projects it is just not opportune to point out a need to skill up, so everybody just accepts whatever in PRs and quality never gets any better.

On the other end of the spectrum you hear sentences starting with: "It would help me to understand this more easily, if ...".

Guess, what happens over time in these teams?

reactordev• 11 months ago

Boy if I had a dollar for every “we’ve been doing it wrong” posts.

The issue with this stance is, it’s not a zero sum game. There’s no arriving to a point where there isn’t a cognitive load on the task you’re doing. There will always be some sort of load. Pushing things off so that you reduce your load is how social security databases end up on S3.

Confusion comes from complexity. Not a high cognitive load. You can have a high load and still know how it all works. I would better word this as Cognitive load increases stress as you have more things to wrestle about in your head. Doesn’t add or remove confusion (unless that’s the kind of person you are), it just adds or removes complexity.

An example of a highly complex thing with little to no cognitive load due to conditioning, driving an automobile. A not-complex thing that imparts a huge cognitive load, golf.

rowanG077• 11 months ago

It's always interesting that many people who push the cognitive load argument also push for simpler languages. To me once I have learned a language well the features it has don't add to the cognitive load. they become basically second nature. It even has a great benefit, many things that are explicit in simple languages because there is no language support fall away in more complex languages. So more complex languages reduce cognitive load, at least for me.

aDyslecticCrow6• 11 months ago

Complex languages can give the programmer powerful tools to abstract things badly. But those powerful tools can also help make the code clearer if used right. (I'm a real sucker for a map().filter().map().sort().unwrap(), and feel the same logic becomes so unruly to understand if converted to a large loop)

I think the sentiment that we should use simpler languages comes abuse of powerful features. Once we've meta-programmed the entire program logic with a 12 layer deep type tree or inheritance chain... we may realize we abused the tool in a way a simple language would have stopped.

But at the same time...checking a errno() after a function call just because the language lack result type or exception handling, is clearly too simple. A minor increase in language complexity would have made the code much clearer.

weiliddat6• 11 months ago

Exactly, cognitive load is dynamic not static, and you can actually hold many more things in working memory than the oft-repeated 3-7 items (that's more if you're trying memorize and recall unrelated, novel items).

Once you commit a particular concept to long-term memory and it's not "leaky" (you have to think through the internal behavior/implementation details), then now you have more tools and ways to describe a collective bunch of lower-level concepts.

That's the same feeling programmers used to more powerful languages have to write less powerful languages — instead of using 1 concept to describe what you want, now you have to use multiple things. It's only easier if you've not grokked the concept.

tester756• 11 months ago

So more complex languages reduce cognitive load, at least for me.

Even C++ and all it's crazy features of last 5-10 years?

nibblenum• 11 months ago

Still processing this article, but so far enjoying that it opens with some humour, and also shows off logistics ideas that are not locked into one domain if you zoom out. Thank you :)

oh_my_goodness2• 11 months ago

I would love to have four chunks in my head. I feel like I have to start writing when I get to #3.

perlgeek• 11 months ago

I think the origin of the "four chunks in short-term memory" comes from giving people tasks to calculate some numbers, and seeing after how many digits they became noticeably slower.

A fact that you need to remember about code might use up more or less short-term memory in a human brain compared to a digit or a number, so don't be ashamed if your number is 3 instead of 4.

I also think that my working memory was better when I was 20ish, now at 41 I already feel less fits in and I forget it faster.

supportengineer• 11 months ago

Large software projects built by humans will always be doomed to fail, because humans like to build the new, and nobody likes to maintain the old.

mdaniel5• 11 months ago

I'm pretty sure this entire thread is filled with "nobody likes to maintain the pile of ifs", since I doubt very seriously it's the age that jams people up, it's finding the correct place to make a surgical change that only produces the net-new behavior without blowing up the world. I guess the rest of that is that often the older a codebase is, the more revenue stream in impacts if something goes wrong

tenacious_tuna• 11 months ago

I've very much enjoyed maintaining or optimizing or hardening existing systems--I can just never convince my leadership to let me do that.

My current org has a terrible case of not-invented-here syndrome, and it's so easy to pitch new projects that solve something that there's already an existing tool for, or building a new feature. We would love to spend time just working within our existing systems and fixing crap abstractions we made under the deadline-gun, but we're not "allowed" to.

[...] humans like to build the new, and nobody likes to maintain the old

I think this is certainly true at organizational scale, but most of the people I've met are change-resistant overall.

bauble• 11 months ago

Humans are the worst programmers, except for all other programmers.

weiliddat6• 11 months ago

While I support the goal of article, reducing extraneous cognitive load, I think some of the comments, and the article are missing a key point about cognitive load — it depends on the existing mental model the reader/author/developer has about the whole thing. There is no universal truth to reducing cognitive load like reducing abstractions / not relying on frameworks.

Reducing cognitive load doesn't happen in a vacuum where simple language constructs trump abstraction/smart language constructs. Writing code, documents, comments, choosing the right design all depend upon who you think is going to interact with those artifacts, and being able to understand what their likely state of mind is when they interact with those artifacts i.e. theory of mind.

What is high cognitive load is very different, for e.g. a mixed junior-senior-principal high-churn engineering team versus a homogenous team who have worked in the same codebase and team for 10+ years.

I'd argue the examples from the article are not high cognitive load abstractions, but the wrong abstractions that resulted in high cognitive load because they didn't make things simpler to reason about. There's a reason why all modern standard libraries ship with standard list/array/set/hashmap/string/date constructs, so we don't have manually reimplement them. They also give a team who is using the language (a framework in its own way) common vocabulary to talk about nouns and verbs related to those constructs. In essense, it is reducing the cognitive load once the initial learning phase of the language is done.

Reading through the examples in the article, what is likely wrong is that the decision to abstract/layer/framework is not chosen because of observation/emergent behavior, but rather because "it sounds cool" aka cargo cult programming or resume-driven programming.

If you notice a group of people fumble over the same things over and over again, and then try to introduce a new concept (abstraction/framework/function), and notice that it doesn't improve or makes it harder to understand after the initial learning period, then stop doing it! I know, sunk cost fallacy makes it difficult after you've spent 3 months convincing your PM/EM/CTO that a new framework might help, but then you have bigger problems than high cognitive load / wrong abstractions ;)

zakirullin15• 11 months ago

There's a chapter about mental models: https://github.com/zakirullin/cognitive-load?tab=readme-ov-f...

weiliddat6• 11 months ago

Yes, and I hope I made a point that it's not the right approach always.

If you've internalized the mental models of the project into your long-term memory, you won't experience a high cognitive load ... If you keep the cognitive load low, people can contribute to your codebase within the first few hours of joining your company.

Yes, if you really are having new joiners often, and you expect them to be onboarded quickly. That happens for a specific segment of the software industry, not generally.

If you're working with the same people all the time, and it's the nth time someone made a mistake in a huge frontend JS codebase (pre-Angular/React) trying to wrangle with plain events and DOM state, a new framework (like React and co) that abstracts away events and DOM state management was perhaps the right choice.

This way of thinking and abstraction is so popular now that it's taken almost for granted by people who started learning programming for the web recently. For these people, using plain JS might be higher cognitive load, so

Lots of cool architectures, fancy libraries and trendy technologies were used. In other words, the author had created a high cognitive load for us.

that's not a universal statement.

Do I personally believe there are better levels of abstraction, and simpler frameworks than React, Express, Django, Spring, Laravel, etc.? Yes, but if the developers you are hiring/teaching/working with are familiar with those, and it's working for them, then maybe that is the right choice to use.

The main statement I agree with in the article (apart from the goal of reducing cognitive load) comes much later, in

So, why pay the price of high cognitive load for such a layered architecture, if it doesn't pay off in the future? Plus, in most cases, that future of replacing some core component never happens.

where the main problem is having the wrong reasons or wrong choice of architecture. It's not necessarily that abstraction/architecture is bad. I feel like the message of "you should keep it simple" is overemphasized in the rest of the article. Maybe that's in response to overengineering in the industry or the author's experience.

marcelr• 11 months ago

while i think this is generally good advice, i also think reality isn't easy to define

i like what others would call complexity, i always have, and have from very very early on been mindful of that, i think to a fault since i no longer trust my intuition

is it good to try to turn wizards into brick layers? is there no other option?

piskov• 11 months ago

This is your annual reminder to watch “Simple made easy” by Rich Hickey

https://youtu.be/SxdOUGdseq4

layer83• 11 months ago

Then QA engineers come into play: "Hey, I got 403 status, is that expired token or not enough access?"

To be fair, the HTTP status line allows for arbitrary informational text, so something like “HTTP/1.1 401 JWT token expired” would be perfectly allowable.

madman2890• 11 months ago

“Smart developer’s quirks” tend to peak in 3-8 years of experience and fade off thereafter. A hipster will never fade off and instead continue hipster coding alongside their identity in perpetuity.

riedel• 11 months ago

Speaking only of intrinsic and extraneous cognitive load oversimplifies things. This works for tasks of pilots (see e.g. NASATLX scores).

However, if new information that needs to be learned is in the game there is also germane cognitive load [0]. It is a nice theory, however, practically there is unfortunately no easy way to separate them and look at them totally independently.

[0] https://mcdreeamiemusings.com/blog/2019/10/15/the-good-the-b...

semiinfinitely• 11 months ago

The ability to create code that imposes low cognitive load on others not only is a rare and difficult skill to cultivate- it takes active effort and persistence to do even for someone who already has the ability and motivation. I think fundamentally the developer is computing a mental compression of the core ideas - distilling them to their essence - and then making sure that the code exposes only the minimum essential complexity of those ideas. not easy and rare to see in practice

bombela• 11 months ago

And if you do it really well, people think it must have been such an easy problem to solve all along. Since everything always appears so obvious in insight.

While the castle of cards of unfathomable complexity is praised for visibly hard work and celebrated with promotions.

an0malous• 11 months ago

“When you do things right, people won’t be sure you’ve done anything at all”

Tarks• 11 months ago

Plus rarely survives requirements/context changing because most abstractions are leaky.

My favourite frameworks are written by people smart enough to know they're not smart enough to build the eternal perfect abstraction layers and include 'escape hatches' (like getting direct references to html elements in a web UI framework etc) in their approach so you're not screwed when it turns out they didn't have perfect future-sight.

DrewADesign2• 11 months ago

This is also true of interface/UX/interaction design. Most developers are really skilled at maintaining a higher cognitive load than most, and the interfaces that work best for less technical people often frustrate developers, who want everything in front of them, visible, at all times because they intuitively know what’s important. Interfaces created by developers might click with other devs, but often bewilder less technical people. It’s really hard to design a tool that less technical people can use intuitively to solve complex problems without wanting to throw their electronics out the window.

dodomodo• 11 months ago

This was maybe a problem years ago, but I don't think its a pro lem these days. I see many more cases of the opposite problem, interfaces that are meant of technical users but are designed using modern mobile centric paradigms, over emphasizing negative space and progressive disclosure.

this is also a problem for tools designed for non-technical users for complex tasks that are performed frequently. your power users needs a powerful interface even if they are less technical.

jama2117• 11 months ago

It is! But it’s also a bonus rather than a requirement for a lot of firms. For proof, look at any major codebase.

BenkaiDebussy2• 11 months ago

I think one issue is that some people just find very different things intuitive. Low cognitive load for one person might be high cognitive load for another.

Because of some quirk of the way my brain works, giant functions with thousands of lines of code doesn't really present a high cognitive load for me, while lots of smaller functions do. My "working memory" is very low (so I have trouble seeing the "big picture" while hopping from function to function), while "looking through a ton of text" comes relatively easily to me.

I have coworkers who tend to use functional programming, and even though it's been years now and I technically understand it, it always presents a ton of friction for me, where I have to stop and spend a while figuring out exactly what the code is saying (and "mentally translating" it into a form that makes more sense to me). I don't think this is necessarily because their code inherently presents a higher cognitive load - I think it's easier for them to mentally process it, while my brain has an easier time with looking at a lot of lines of code, provided the logic within is very simple.

TZubiri3• 11 months ago

And ironically, writing code that is maintainable on the long run and imparts a low cognitive load on successive developers is itself a cognition consuming effort.

In tradeoff engineering, maintainability over the long term is one of the many variables to optimize, and finite resources need to be alloted to it.

When I read this article I get the feeling that it's more likely that he is obsessing over maintainability over the long term while his app has a user count of zero. This malady usually comes from the perspective of being a user, one finds that the experience of writing some code is a "bad experience" so they strive to improve it or learn how to build a good "coder experience", the right answer is to understand that one is stepping into the shoes of the plumber, and it will be shitty, just gotta roll up your sleeves.

Don't get me wrong, there's a lot of wisdom here, but to the extent that there is, it's super derivative and well established, it's just the kind of stuff that a developer learns on their first years of software by surfing the web and learning about DRY, KISS and other folklore of software. To some extent this stuff is useful, but there's diminishing returns and at some point you have to throw shit and focus on the product instead of obsessing over the code.

mercenario• 11 months ago

I learned a lot this in competitive programming. I used to write code that were 3-5x the size of the intended solution. There are many reason why you could write a worse/bigger solution but sometimes when I compared both solutions one thing I could notice is that I could remove a lot of things from my solution until nothing could be removed anymore and the final solution would really seem like it were the essence of the problem.

But even if the intended solution seemed simpler, it could be much harder to discover it.

david_draco• 11 months ago

Unit and Integration testing is great for decreasing cognitive load too. When you are staring at an error stack trace of a complex code base, and go through mentally what could have played out to cause this, it's great to have confidence in components due to testing. Hypothesis/QuickCheck is allows dropping entire classes of worries.

supernuova• 11 months ago

Yes, exactly! If you can trust that each unit is working in all the ways covered in the tests, you can focus on the unit you are developing and not have to keep the other unit in your mind while working on it. And if there is an untested edge case you think might be the cause, you can test that edge case independently from the unit where the issue is occurring, and confirm if it produces the expected result.

Good, trusted unit tests are the difference between encapsulation reducing or increasing/complicating cognitive load. (And similar but between components for integration tests).

That being said, there will be rare times that the issue is due to something that is only an edge case due to an implementation detail several units deep, and so sometimes you do still need the full picture, but at least it lets you save doing that until you're stumped, which IMO is well worth it if the code is overall well-designed and tested.

00yogi• 11 months ago

A similar design principle is called “APIs should be deep, not wide”: https://unterwaditzer.net/2024/api-wrappers.html

zakirullin15• 11 months ago

Thanks! I might link it to the article.

xmprt2• 11 months ago

This is one of the reasons I fear AI will harm the software engineering industry. AI doesn't have any of these limitation so it can write extremely complex and unreadable code that works... until it doesn't. And then no one can fix it.

It's also why I urge junior engineers to not rely on AI so much because even though it makes writing code so much faster, it prevents them from learning the quirks of the codebase and eventually they'll lose the ability to write code on their own.

fsckboy2• 11 months ago

AI can write extremely complex and unreadable code that works... until it doesn't. And then

AI can fix it

I'm not defending or encouraging AI, just saying that argument doesn't work

xmprt2• 11 months ago

I'm talking about cases where even AI can't fix it. I've heard of a lot of stories where people vibe code their applications to 80% and then get stuck in a loop where AI is unable to solve their problems.

It's been well documented that LLMs collapse after a certain complexity level.

mupuff12343• 11 months ago

Or maybe it will actually increase the quality of software engineering because it will free up the cognitive load from thinking of the low level design to higher level architecture.

dsego7• 11 months ago

That's my fear, it will become a sort of a compiler. Prompts will be the code and code will be assembly, and nobody will even try to understand the details of the generated code unless there is something to debug. This will cause the codebases to be less refined with less abstraction and more duplication and bloat, but we will accept it as progress.

pessimizer4• 11 months ago

Thus far, and granted I don't have as much experience as others, I just demand that AI simplify the code until I understand everything that it is doing. If I see it doing something in a convoluted way, I demand that it does it in the obvious way. If it's adding too many dependencies, I tell it to remove the goofy ones and write it the long way with the less capable stdlib function or helped by something that I already have a dependency on.

It's writing something for me, not for itself.

balder1991• 11 months ago

Yeah, as much as I don’t like to use AI to write large portions of code, I’m using it to help me learn web development and it can feel like a following a tutorial, but tailored to the exact project I want.

My current approach is creating something like a Gem on Gemini with custom instructions and the updated source code of the project as context.

I just discuss what I want, and it gives me the code to do it, then I write by hand, ask for clarifications and suggest changes until I feel like the current approach is actually a good one. So not really “vibe-coding”, though I guess a large number of software developers who care about keeping the project sane must be doing this.

inkyoto• 11 months ago

It's also why I urge junior engineers to not rely on AI so much because even though it makes writing code so much faster […]

I am afraid, the cat is out the bag, and there is no turning back with GenAI and coding – juniors have got a taste of GenAI assisted coding and will persevere. The best we can do it educate them on how to use it correctly and responsibly.

The approach I have taken involves small group huddles where we talk to each other as equals, and where I emphasise the importance of understanding the problem space, the importance of the depth and breadth of knowledge, i.e. going across the problem domain – as opposed to focusing on a narrow part of it. I do not discourage the junior engineers from using GenAI, but I stress the liability factor and the cost: «if you use GenAI to write code, and the code falls apart in production, you will have a hard time supporting it if you do not understand the generated code, so choose your options wisely». I also highlight the importance of simplicity over complexity of the design and implementation, and that simplicity is hard, although it is something we should strive for as an aspiration and as a delivery target.

I reflect on and adjust the approach based on new observations, feedback loop (commits) and other indirect signs and metrics – this area is still new, and the GenAI assisted coding framework is still fledging.

edem• 11 months ago

id argue that it already harmed the industry

arnonejoe• 11 months ago

"Domain-driven design has some great points, although it is often misinterpreted”. Agreed. The worst shops I’ve ever worked in are ones where the DDD/evans/fowler orthodoxy has run amok.

lilerjee2• 11 months ago

Cognitive Load is not what matters, Solving problems is what matters.

"Cognitive Load" is a buzzword which is abstract.

Cognitive Load is just one factor of projects, and not the main one.

Focus on solving problems, not Cognitive Load, or other abstract concepts.

Use the simple, direct, and effective method to solve problems.

Cognitive Load is relative, it is a high Cognitive Load for one person, but low cognitive load for another person for the same thing.

adolph• 11 months ago

"Cognitive Load" may be a buzzword, and not well defined, and that doesn't mean it isn't a useful concept for evaluating different approaches toward solving problems that may extend the useful life of that solution instead of reinventing yet another wheel.

Getting to a better understanding of "cognitive load" does seem useful. Some things are "easier" to understand than others. Could things that are less efficient to understand be formulated in a way that is more efficient?

I have a notion that "cognitive load" is related to the human's ability to gain and maintain attention to mentally ingesting a solution (along with the problem the solution putatively solves). Interesting reads for this include McGilchrist's Master and His Emissary, and Carolyn Dicey Jennings' "I attend, therefore I am," [0], who was interviewed on the Rutt podcast [1].

0. https://aeon.co/essays/what-is-the-self-if-not-that-which-pa...

1. https://jimruttshow.blubrry.net/the-jim-rutt-show-transcript...

tartoran• 11 months ago

Cognitive Load is not what matters, Solving problems is what matters.
Use the simple, direct, and effective method to solve problems.

You seem to contradict yourself, while you mention cognitive load is not what matters you prescribe a way to lower cognitive load. I've seen projects explode in complexity and then die and that was mainly to unmanageable cognitive load required to make changes.

lilerjee2• 11 months ago

Solving problems is the purpose and focus.

How to solve problems?

The simple, direct, and effective method is good one method sometimes, not all time. For example, use very complicated method to obfuscate code in order to increase the difficulty of cracking, and there are many environments to use complicated code or methods.

So one is the purpose, one is the method.

Do not think "Lower Cognitive Load" is the purpose.

"Lower Cognitive load" is just the by-product sometimes, not the purpose.

vdupras2• 11 months ago

I don't know, I'm seduced by the elitist approach: code with a high cognitive load keeps mediocre developers away.

Case in point: Forth. It generally has a heavy cognitive load. However, Forth also enables a radical kind of simplicity. You need to be able to handle the load to access it.

The mind can train to a high cognitive load. It's a nice "muscle" to train.

Should we care about cognitive load? Absolutely. It's a finite budget. But I also think that there are legitimate reasons to accept a high cognitive load for a piece of code.

One might ask "what if you need to onboard mediocre developers into your project?". Hum, yeah, sure. In that case, this article is correct. But being forced to onboard mediocre developers highlights an organizational problem.

winwang2• 11 months ago

This is an interesting take. I have a somewhat orthogonal viewpoint -- rather than "heavy cognitive load", I think that going somewhat off-mainstream is good for attracting, on average, better devs. For example, it's likely that the average Haskell dev spends more time honing their craft than the average Java dev. The article kind of touches on this (e.g. FP "vs" the more popular OOP) with familiarity vs simplicity though.

noportro• 11 months ago

code with a high cognitive load keeps mediocre developers away.

That's true and it's a positive thing but the downstream consequences are often painful. We had a c/c++ project with complex memory management and heavy multithreadding, written that way because the superstar developer could handle the cognitive load and found the assignment intellectually challenging. That was great until they left for the next job.

We were left fighting a codebase with a big cognitive load, so we were desperately dependent on hiring more superstars just for routine maintenance. We eventually concluded that this wasn't a sustainable model and rewrote the system in plain old python. Much happier now.

vdupras2• 11 months ago

This is what I mean by "organizational problem". I understand that sometimes -- in fact most of the times -- you need to onboard mediocre programmers. But on the other hand, it's really great when you don't have to.

haffi112• 11 months ago

The section on nested ifs reminded be of being a Nevernester: https://www.youtube.com/watch?v=CFRhGnuXG-4 (it's a short [~8 min], fun watch)

AlexCoventry2• 11 months ago

He should cite John Ousterhout, IMO. He's clearly influenced by Ousterhout's (excellent) work.

zakirullin15• 11 months ago

And I did it a few times :) He knows about the article, we talked about it.

roadbuster• 11 months ago

Lucky to have an opportunity to chat with him! Did he have any specific feedback on your essay?

AlexCoventry2• 11 months ago

Heh, apologies. Should have Ctrl+F'd.

dennisy• 11 months ago

Whilst I agree with lots of ideas in this piece, I fell out of love with it when clicking into the discussion on what should be done instead of using a layered architecture.

The author makes valid points but they are vacuous and do not provide concrete alternatives.

Many engineering articles disappoint me in this way, I get hyped by all the “don’t dos”, but the “do dos” never come.

zakirullin15• 11 months ago

Software engineering is a relatively immature field. Nobody knows how to cook it in a proper way. What we know for sure is how to fail (point of the article). There was an analogy about building bridges and writing software. Building a bridge is boring, it's a very mature engineering field, and it's clearly known how to do it the best way possible. Software development is far from it. Unknown unknowns, ever changing requirements, different mental models in people's brains...

trentnix• 11 months ago

Cognitive load and the benefits of simplification aren't just for systems and code. Reducing cognitive load is critically important in delivering good requirements. It enables engineers to focus on the technical and organization aspects of the solution, not interpreting the problem.

The fact is, despite all the process and pipelines and rituals we've invented to guide how software is made, the best thing leadership can do is to communicate incremental, unambiguous requirements and provide time and space for your engineers to solve the problem. If you don't do that, none of the other meetings and systems and processes and tools will matter.

guerrilla• 11 months ago

isValid = val > someConstant
isAllowed = condition2 || condition3
isSecure = condition4 && !condition5
// , we don't need to remember the conditions, there are descriptive variables
if isValid && isAllowed && isSecure {
...
}

I literally relaxed in my body when I read this. It was like a deep sigh of cool relief in my soul.

e402• 11 months ago

This is why I make lists. Of everything. Checklists for technical processes (work and personal). Checklists for travel. Little "how to" docs on pretty much everything I do that I'm sure I won't remember past a week.

It completely removes the stress of doing things repeatedly. I recently had to do something I hadn't done in 2 years. Yep, the checklist/doc on it was 95% correct, but it was no problem fixing the 5%.

mettamage• 11 months ago

In like Apple Notes or what do you store the checklists in?

germandiago3• 11 months ago

Depending on the task the most effective way I found sometimes is a hand-written paper stuck on a wall.

Why so? It is always in front of you, it reminds you what you need to do and does not get out of sight, which helps keep the focus.

When you bury it or set it somewhere else it is very easy to bury it.

e4325f• 11 months ago

I use Apple Reminders

ajuc3• 11 months ago

Txt files are hard to beat

computerdork3• 11 months ago

I like the digital note-taking tools, Evernote and Onenote - actually, used to use Evernote, but it started slowing down after my notebooks became too large, so switched to Onenote.

And eventhough Onenote is MS product and Evernote was the original that OneNote copied off of, OneNote is a better engineered piece of software (I have tons of notes and a few of them very large documents), and Onenote rarely has problems.

mimischi• 11 months ago

I don’t think there’s a correct answer here. Whatever floats your boat. Do you want to scribble things by hand into a physical notebook? Great! Want to use Notepad on Windows for .txt? Or create a .docx using Word?

Don’t follow trends and seek the “next best way to hack your productivity”. Most of those things are snake oil and a waste of time. Just use whatever you have available and build a process yourself. That’s what most people have done that are successful in applying this. They just use the tool they are comfortable with, and don’t over engineer for the sake of it

e402• 11 months ago

Switched to Apple Notes recently. Used to use org mode, but the apps on iOS ... just bad.

But, I use different things for different situations.

For work, I use text files in a "howto/" subdirectory of a main repo.

germandiago3• 11 months ago

I am kind of a bit lazy person at times. But when I need to absolutely not to forget anything that can become messy, a checklist is difficult to beat and as you say, it removes all the stress: you elaborate it and when the time comes, keep applying it or applying all at once.

It works very well for me.

schrectacular• 11 months ago

Temporal cognitive load reduction A.K.A. "thanks, past self!"

computerdork3• 11 months ago

Yeah, my OneNote notebook is huge now, littered with checklists, processes, and just notes on different subjects. It's like a secondary memory for me at this point, like longterm storage for rarely used but important info.

Xmd5a• 11 months ago

The right way to do it is to have one person (preferably you) go over the checklist, while someone else (typically a son) do the actual thing.

rossant• 11 months ago

Same. Like what to take in my luggage. Grocery list. To do list. And everything else. I use Dynalist. Great tool. My secret super power, by those who also made Obsidian.

ivansavz• 11 months ago

+1 for lists. I used to procrastinate and suffer every year to do my taxes. Always submit last minute (stress) or late (stress + penalties), but ever since I created a checklist for all the steps (data extractions, data transform in Excel, data loading into tax software, etc.) the tax season is no longer this bad. It still takes me a day, but no stress... just grind though the checkboxes!

ChrisMarshallNY• 11 months ago

There's some good stuff in the posting.

Certainly giving me some pause for thought, in my own work.

holysoles• 11 months ago

Great read. At my last job, everything was quite monolithic when I joined, and I led the crusade to move to more segmented, module-driven development. There was definitely a period where I eventually swung too far in that direction and only realized it after a dependency issue led to an escalation.

Hopefully someone can learn from this before they spin a complex web that becomes a huge effort to untangle.

jakobov• 11 months ago

Yes this is the central theme in https://codeisforhumans.com/

andix5• 11 months ago

I had the exact same experience with layered architectures like described in this article. Avoid them as much as possible, naive and simple code is often better. It might look messy on the surface, and the layered code might look much cleaner. Until you drown in indirections, that are impossible to keep track of.

zakirullin15• 11 months ago

It seems like some engineers have emotional attachment to all these layered architectures. Explaining or giving them examples of failed projects (based on this architecture) doesn't help.

andix5• 11 months ago

Cargo cults

shakesbeard• 11 months ago

We've only made good experiences with layered architecture (onion architecture in particular, which is quite straight forward). We also never built it with the idea in mind to ever replace the storage engine. No, the big, big benefit has been that we can test everything without ever mocking a single class.

I also don't get the point about "going back to IoC" ... how is that mutually exclusive from using a layered architecture. This section was weird and didn't offer any good alternative.

dope9967• 11 months ago

Feels like the author completely misunderstood at least one of the fundamental and basic concepts of DDD - writing how it is only about the problem and not the solution space, where it is actually very clearly about both - but still decided to write down a very sure judgement of it. Disappointing.

kadutskyi• 11 months ago

Tidy first? book gives lots of such advice. Very helpful.

physidev• 11 months ago

I think the viewpoint articulated in this post fits quite well with the one expressed in the often-shared "Programming as Theory-building" article (I think it was shared here just a few days ago).

Scientists, mathematicians, and software engineers are all really doing similar things: they want to understand something, be it a physical system, an abstract mathematical object, or a computer program. Then, they use some sort of language to describe that understanding, be it casual speech, formal mathematical rigor, scientific jargon -- or even code.

In fact, thinking about it, the code specifying a program is just a human-readable description (or "theory", perhaps) of the behavior of that program, precise and rigorous enough that a computer can convert the understanding embodied in that code into that actual behavior. But, crucially, it's human readable: the reason we don't program in machine code is to maximize our and other people's understanding of what exactly the program (or system) does.

From this perspective, when we write code, articles, etc., we should be highly focused on whether our intended audience would even understand what we are writing (at least, in the way that we, the writer, seem to). Thinking about cognitive load seems to be good, because it recognizes this ultimate objective. On the other hand, principles like DRY -- at least when divorced from their original context -- don't seem to implicitly recognize this goal, which is why they can seem unsatisfactory (to me at least). Why shouldn't I repeat myself? Sometimes it is better to repeat myself!? When should I repeat myself??

If you want to see an example of a fabulous mathematician expressing the same ideas in his field (with much better understanding and clarity than I could ever hope to achieve), I highly recommend Bill Thurston's article "On proof and progress in mathematics" <https://arxiv.org/abs/math/9404236>.

insanebrain• 11 months ago

I love love love monorepo + fat encapsulated modules + a couple of deployables. Why does the software industry create fake complexity/creativity in the craft? Fashion/hype architectures for dopamine and fulfilment. You're just wasting energy finding new ways to create machine code for hardware. Why not get creative in the hardware and actually make something new? Another thing that really grinds my gears, is how many human hours are poured into js frameworks instead of improving browsers. What an utter waste of time. Maybe mediocre engineers like me who could never design a CPU or extend a browser need to feel seen by embracing a new domain whatever concept to make us feel warm and fuzzy but not really innovate the real hard things that move the needle.

zakirullin15• 11 months ago

Agreed on every point! From what I observed, some engineers try to express themselves through exciting architectures. They are proud of it, they get their dopamine. Their craft can't be simple, if it is simple then they are dull too. At some point in time some of them stop associating their code with themselves, and take somewhat business approach. Most of them do not pass this point, unfortunately.

zakirullin15• 11 months ago

I also find JS and all the infrastructure very mentally taxing. Building a legacy project via some esoteric and already out-of-fashion build system is so painful. Thousands of dependencies, hundreds of issues and warnings...

gtzi• 11 months ago

This is also a proper framework for evaluating AI replies – they do not only need to be appropriate, they also need to consume the minimum cognitive load for parsing.

computerdork3• 11 months ago

I completely agree with every in this article, but seems like it's just at different way of looking at the well-known software-engineering concept of "complexity." Yeah, the main difference is cognitive load is considering the complication of the system from how it effects the developer, while complexity focuses on the amount of complications in the system itself.

Yeah, if you go through this article and replace most of the places where it mentions "cognitive load" with "complexity," it still makes sense.

Yeah, this isn't a criticism of the article - In fact, there are important difference, like having more of a focus on what the dev is experiencing handling the complications of the system - But for those really interested in its concept, may want to learn about complexity too, as there is a lot of great info on this.

sltr• 11 months ago

Any discussion of cognitive load in programming needs to include awareness of this book:

The Programmer's Brain: What every programmer needs to know about cognition. By Felienne Hermans

https://www.manning.com/books/the-programmers-brain

neonrider2• 11 months ago

Love it. Make code accessibility a first-class citizen. Turn the rule books and their principles into guidelines. A smart coder knows to follow rules. A master knows code is meant to be read and develops contextual awareness for when and why to break a rule, or augment it, as the case may be. So, reintroduce judgment and critical thinking in your coding practice. Develop an intuitive feel for the cognitive costs and trade-offs of your decisions. Whether you choose to duplicate or abstract, think of the next person (who sometimes is you in six months).

For those asking why author doesn't come up with their own new rules that can then be followed, this would just be trading a problem for the same problem. Absentmindedly following rules. Writing accessible code, past a few basic guidelines, becomes tacit knowledge. If you write and read code, you'll learn to love some and hate some. You'll also develop a feel for heavy handedness. Author said it best:

It's not imagined, it's there and we can feel it.

We can feel it. Yes, having to make decisions while coding is an uncomfortable freedom. It requires you to be present. But you can get used to it if you try.

zakirullin15• 11 months ago

Thanks a lot! You've nailed it :)

rhameetman• 11 months ago

Make code accessibility a first-class citizen.

This is a good article but the main thing that bugs me about it is that the author completely disregards germane overhead.

Germane overhead is about recognition and practice and, at scale, it matters just as much.

Intrinsic and extraneous overhead is about the information itself and how it’s presented.

Germane overhead is about the receiver so in order to make code accessibility a first-class citizen you can’t ignore it.

PandaRider• 11 months ago

This is correct. To delve into a topic about cognitive load without talking about germane overhead disqualifies this article (i.e. similar to extraneous overhead in terms of effort but germane overhead is beneficial. Because it helps the coder's reading ability.)

The examples are good but every reader must not have the takeaway that every effortful code is bad (e.g. haskell is extremely hard to read at first but every developer swears it has very high intrinsic cognitive load)

neonrider2• 11 months ago

You might have opened the article thinking that it was going to be a discussion on cognitive load theory in general. It's not and I don't believe it needed to be for its purpose, since it's been well framed: code. Intrinsic, extraneous, germane loads? Why talk in abstract? The field of professional programming is an exemplar that evidences all those concepts. We pretty much live the theory. Programming is inherently complicated, we know how/why. We tend to needlessly add to the complexity, we know how/why. We are also notoriously ignorant, oblivious even, of our minds' true limitations and have strange beliefs regarding our abilities. Check, check, and check. Article can just speak plainly. "Don't make complicated things more complicated than they need to be. You're only human".

exclipy3• 11 months ago

This was my main takeaway from A Philosophy Of Software Design by John Ousterhout. It is the best book on this subject and I recommend it to every software developer.

Basically, you should aim to minimise complexity in software design, but importantly, complexity is defined as "how difficult is it to make changes to it". "How difficult" is largely determined by the amount of cognitive load necessary to understand it.

zakirullin15• 11 months ago

That's best book on the topic! The article was inspired by this exact book. And John is a very good person, we discussed a thing or two about the article.

exclipy3• 11 months ago

Oh! I was surprised you didn't link or mention the book

bsenftner• 11 months ago

Which is why I consider DRY (Don't Repeat Yourself) to be an anti-rule until an application is fairly well understood and multiple versions exist. DO repeat yourself, and do not create some smart version of what you think the problem is before you're attempting the 3rd version. Version 1 is how you figure out the problem space, version 2 is how you figure out your solution as a maintainable dynamic thing within a changing tech landscape, and version 3 is when DRY is look at for the first time for that application.

hinkley7• 11 months ago

Some people use a gardening metaphor for code, and I think that since code is from and for humans, that’s not a terrible analogy. It’s organic by origin if not by nature.

When you’re dealing with perennial plants, there’s only so much control you actually have, and there’s a list of things you know you have to do with them but you cannot do them all at once. There is what you need to do now, what you need to do next year, and a theory of what you’ll do over the next five years. And two years into any five year plan, the five year plan has completely changed. You’re hedging your bets.

Traditional Formal English and French gardens try to “master” the plants. Force them to behave to an exacting standard. It’s only possible with both a high degree of skill and a vast pool of labor. They aren’t really about nature, or food. They’re displays of opulence. They are conspicuous consumption. They are keeping up with the Joneses. Some people love that about them. More practical people see it as pretentious bullshit.

I think we all know a few companies that make a bad idea work by sheer force of will and overwhelming resources.

zahlman4• 11 months ago

DRY isn't about not reimplementing things; it's about not literally copying and pasting code. Which I have seen all the time, and which some might find easier now but will definitely make the system harder to change (correctly) at some point later on.

martinpw• 11 months ago

Closely related to the Rule of Three - ok to duplicate once, but if it is needed a third time, consider refactoring: https://en.wikipedia.org/wiki/Rule_of_three_(computer_progra...

I think it's a pretty good compromise. I have tried in the past not to duplicate code at all, and it often ends up more pain than gain. Allow copy/paste if code is needed in two different places, but refactor if needed in three or more, is a pretty good rule of thumb.

tialaramex2• 11 months ago

I think more than a few people have recommended waiting until the 3rd or 4th X before you say OK, Don't Repeat Yourself we need to factor this out. That's where my rule of thumb is too.

Deliberately going earlier makes sense if experience teaches you there will be 3+ of this eventually, but the point where I'm going to pick "Decline" and write that you need to fix this first is when I see you've repeated something 4-5 times, that's too many, we have machines to do repetition for us, have the machine do it.

An EnableEditor function? OK, meaningful name. EnablePublisher? Hmm, yes I understand the name scheme but I get a bad feeling. EnableCoAuthor? Approved with a stern note to reconsider, are we really never adding more of these, is there really some reason you can't factor this out? EnableAuditor. No. Stop, this function is named Enable and it takes a Role, do not copy-paste and change the names.

cyberax4• 11 months ago

DRY means something completely different. It means that there should be just one source of truth.

Example: you have a config defined as Java/Go classes/structures. You want to check that the config file has the correct syntax. Non-DRY strategy is to describe its structure in an XSD schema (ok, ok JSON schema) and then validate the config. So you end up with two sources of truth: the schema and Java/Go classes, they can drift apart and cause problems.

The DRY way is to generate the classes/structures that define the config from that schema.

hinkley7• 11 months ago

It’s a pain in the ass to source a copy of this book without giving Jeff Bezos all the money. If anyone reading this thread knows John, could you bring this to his attention?

I even tried calling the bookstore on his campus and they said try back at the beginning of a semester, they didn’t have any copies.

My local book store could not source me a copy, and neither IIRC could Powell’s.

tialaramex2• 11 months ago

That sucks. Ordinarily although a weird volume there's no demand for won't be fast a bookshop should be able to get anything in print. Is there some reason it's specific to this book do you think?

ashurov• 11 months ago

did you try here?: https://www.abebooks.com/book-search/publisher/yaknyam-press...

tverbeure• 11 months ago

Only half joking: I don’t think I trust a book from an author who has inflicted decades of TCL pain on me (and on the entire community of EDA tool users.)

RossBencina• 11 months ago

I know you're only half joking, but I don't think you can pin the blame on John or TCL. Osterhaut's thesis, as I recall, was that there is real benefit to having multiple programming languages working at different levels of the domain (e.g. a scriptable system with the core written in a lower level language). Of course now this is a widespread practice in many domains (e.g. web browsers, numerical computing: matlab, numpy). It's an idea that has stood the test of time. TCL is just one way of achieving that aim, but at the time it was one of few open-source options available. I think scheme/lisp would have been the obvious alternative. AutoDesk went in that direction.

I remember using TCL in the 90s for my own projects as an embeddable command language. The main selling point was that it was a relatively widely understood scripting language with an easily embeddable off-the-shelf open source code base, perhaps one of the first of its kind (ignoring lisps.) Of course the limitations soon became clear. Only a few years later I had high hopes that Python would become a successor, but it went in a different direction and became significantly more difficult to embed in other applications than was TCL -- it just wasn't a primary use case for the core Python project. The modern TCL-equivalent is Lua, definitely a step up from TCL, but I think if EDA tools used Lua there would be plenty of hand-wringing too.

Just guessing, but I imagine that at the time TCL was adopted within EDA tools there were few alternatives. And once TCL was established it was going to be very hard to replace. Even if you ignore inertia at the EDA vendors, I can't imagine hardware engineers (or anyone with a job to do) wanting to switch languages every two to five years like some developers seem happy to do. It's a hard sell all around.

I reckon the best you can do is blame the vendors for (a) not choosing a more fit-for purpose language at the outset, which probably means Scheme, or inventing their own, (b) or not ripping the bandaid off at some point and switching to a more fit-for-purpose language. Blaming (b) is tough though, even today selecting an embedded application language is vexed: you want something that has good affordances as a language, is widely used and documented, easily embedded, and long-term stable. Almost everything I can think of fails the long term stability test (Python, JavaScript, even Lua which does not maintain backward compatibility between releases).

YZF3• 11 months ago

The problem is no set of rules can replace taste, judgement, experience and intuition. Every rule can be used to argue anything.

You can't win architecture arguments.

I like the article but the people who need it won't understand it and the people who don't need it already know this. As we say, it's not a technical problem, it's always a people and culture problem. Architecture just follows people and culture. If you have Rob Pike and Google you'll get Go. You can't read some book and make Go. (whether you like it or not is a different question).

braebo2• 11 months ago

I’m accustomed to this principle as a musician, so it’s been interesting to see it withstand my journey into software.

lokar• 11 months ago

I found the book helpful as a way to organize and express what I already knew

zakirullin15• 11 months ago

I like the article but the people who need it won't understand it

That's true. One doesn't change his mindset just after reading. Even after some mentorship the results are far from satisfying. Engineers can completely agree with you on the topic, only to go and do just the opposite.

It seems like the hardest thing to do is to build a feedback loop - "what decisions I made in past -> what it led to". Usually that loop takes a few years to complete, and most people forget that their architecture decisions led to a disaster. Or they just disassociate themselves.

bb882• 11 months ago

Every rule can be used to argue anything.

Unless it's a rule prohibiting complexity by removing technologies. Here's a set of rules I have in my head.

1. No multithreading. (See Mozilla's "You must be this high" sign)

2. No visitor pattern. (See grug oriented development)

3. No observer pattern. (See django when signals need to run in a particular order)

4. No custom DSL's. (I need to add a new operator, damnit, and I can't parse your badly written LALR(1) schema).

5. No XML. (Fight me, I have battle scars.)

bogdanoff_2• 11 months ago

the people who need it won't understand it

That's not true. There's plenty of beginner programmers who will benefit from this.

ruraljuror• 11 months ago

Software developers don’t arrive fully formed. Rob Pike benefitted from reading a book or two.

safety1st• 11 months ago

The approach that I am trialing with my team now, so far to good results, is as follows.

* Our coding standards require that functions have a fairly low cyclomatic complexity. The goal is to ensure that we never have a a function which is really hard to understand.

* We also require a properly descriptive header comment for each function and one of the main emphases in our code reviews is to evaluate the legibility and sensibility of each function signature very carefully. My thinking is the comment sort of describes "developer's intent" whereas the naming of everything in the signature should give you a strong indication of what the function really does.

Now is this going to buy you good architecture for free, of course not.

But what it does seem to do is keep the cognitive load manageable, pretty much all of the time these rules are followed. Understanding a particular bit of the codebase means reading one simple function, and perhaps 1-2 that are related to it.

Granted we are building websites and web applications which are at most medium fancy, not solving NASA problems, but I can say from working with certain parts of the codebase before and after these standards, it's like night and day.

One "sin" this set of rules encourages is that when the logic is unavoidably complex, people are forced to write a function which calls several other functions that are not used anywhere else; it's basically do_thing_a(); do_thing_b(); do_thing_c();. I actually find this to be great because it's easy to notice and tells us what parts of the code are sufficiently complex or awkward as to merit more careful review. Plus, I don't really care that people will say "that's not the right purpose for functions," the reality is that with proper signatures it reads like an easy "cliffs notes" in fairly plain English of exactly what's about to happen, making the code even easier to understand.

mnsc• 11 months ago

You can't win architecture arguments.

I feel this in my soul. But I'm starting to understand this and accept it. Acceptance seem to lessen my frustration on discussing with architects that seemingly always take the opposite stance to me. There is no right or wrong, just always different trade offs depending on what rule or constraint you are prioritizing in your mind.

heresie-dabord• 11 months ago

Every rule can be used to argue anything.

This is true. However, very few people can clearly explain all the rules.

If they can, they have understood the system and are qualified.

onlinehost• 11 months ago

I bought his book after seeing this talk of his https://youtu.be/bmSAYlu0NcY

swat535• 11 months ago

I've long given up on trying to find the perfect solution for Software. I don't think anyone has really "cracked the code" per se. The best we have is people's wisdom and experiences.

Ultimately, context, industries and teams vary so greatly that it doesn't make sense to quantify it.

What I've settled on instead is aiming for a balance between "mess" and "beauty" in my design. The hardest thing for me personally to grasp was that businesses are indeterministic whereas software is not, thus requirements always shifts and fitting this into the rigidity of computer systems is _difficult_.

These days, I only attempt to refactor when I start to feel the pain when I'm about to change the code.. and even then, I perform the bare minimum to clean up the code. Eventually multiple refactoring shapes a new pattern which can be pulled into an abstraction.

epolanski2• 11 months ago

There is no objective "perfect", because the "perfect" is in the eyes of the reader.

Also, people confuse familiar with simple, they tend to find things simple if they are familiar, even if they are complex (interwine a lot of different things).

ferguess_k3• 11 months ago

I'm struggling with the amount of complexity. As an inexperienced SWE, I found it difficult to put everything into my head when the # of function calls (A) + # of source code files (B) to navigate reach N. In particular, if B >= 3 or A >= 3 -- because, B equals the number of screens I need to view all source code files without Command+Tab/Alt+Tab, and cognitive load increases when A increases, especially when some "patterns" are involved.

But I'm not experienced enough to tell, whether it is my inexperience that causes the difficulty, or it is indeed that the unnecessary complexity tha causes it.

lll-o-lll2• 11 months ago

Humans have a very limited amount of working memory. 3-5 items on average. A savant might be at something like 12. It is trivially easy to blow that with code. OO with code inheritance is a prime example of combinatorial explosion that can lead to more possibilities than atoms in the universe, let alone one persons ability to reason.

Watch ‘Simple made Easy’ by Rich Hickey; a classic from our industry. The battle against complexity is ever ongoing. https://youtu.be/SxdOUGdseq4?feature=shared

seadan833• 11 months ago

Experience helps to recognize intent sooner. That reduces cognitive load. Getting lost 5 levels deep seemingly never stops being a thing, not just you.

brabel3• 11 months ago

You should not need to read every line of code in every file and function to understand what’s going on to the level you need to solve a particular problem. You must make a decision to NOT look deeper at some point on any non- trivial code base. A good program with good names and comments in the appropriate places is what allows you to do exactly that more easily . When you see sort(usernames) in the middle of a function do you need to dive into sort to be able to understand the code in that function?? Probably not, unless you are fixing a bug in how usernames are sorted!

With that said , get good at jumping into definitions, finding all implementations, then jumping back where you were. With a good IDE you can do that at the speed of thought (in IntelliJ that’s Cmb+b, Cmd+Alt+b, Cmd+[ on Mac). I only open more than one file at the same time when comparing them. Otherwise it’s much easier to jump around back and forth (you can even open another function inline if you just want to take a Quick Look, it’s Alt+Space). Don’t use the mouse to do that, things you do all the time can be made an order of magnitude faster via shortcuts. Too many developers I see struggle with that and are embarrassingly slow moving around the code base!

Shorn• 11 months ago

Unsurprisingly, minimising the amount of cognitive complexity is how you get the most out of LLM coding agents. So now have a theoretically repeatable way to measure cognitive load as contextualised to software engineering.

leke• 11 months ago

Yep pretty much. This could literally be notes taken from the book including the phrase itself.

shaimagz• 11 months ago

I’m not reading code anymore, cursor does

alphazard2• 11 months ago

The bit about "smart developer quirks" looks suspiciously like the author only understands code that they have written, or is in a specific style that they recognize. That's not the biggest driver behind cognitive load.

Reducing cognitive load comes from the code that you don't have to read. Boundaries between components with strong guarantees let you reason about a large amount of code without ever reading it. Making a change (which the article uses as a benchmark) is done in terms of these clear APIs instead of with all the degrees of freedom available in the codebase.

If you are using small crisp API boundaries to break up the system, "smart developer quirks" don't really matter very much. They are visible in the volume, but not in the surface area.

hinkley7• 11 months ago

I learned pretty early on that people get really tired of optimization of code that is directly in the call stack they have to breakpoint in. Later on I clocked some of that as code smells pulling attention and analysis time during debug work.

But the trick I found is that if you can extract a function for only the part of the code you’re optimizing/improving, and then make your change in a single commit, two things happen. One, it’s off the code path, so out of site, out of mind. Two, people are more forgiving of code changes they don’t like but can roll back by reverting a single commit. That breaks down a bit with PRs, since they tend to think of the code as a single commit. But the crisp boundaries still matter a lot.

srcreigh• 11 months ago

What do you mean about “people get really tired of optimization of code that is directly in the call stack they have to breakpoint in”? What’s the context where everybody else is using breakpoints?

djmips• 11 months ago

https://news.ycombinator.com/newsguidelines.html

"Please respond to the strongest plausible interpretation of what someone says, not a weaker one that's easier to criticize. Assume good faith."

zakirullin15• 11 months ago

Having a clear and minimalistic API doesn't mean that the underlying code is easy to understand. It's good when things just work and you can use an API, but most of the time you have to dig whatever is under the rug.

alphazard2• 11 months ago

Having a clear and minimalistic API doesn't mean that the underlying code is easy to understand.

Doesn't need to be. The API tells me what it does, hopefully there is a test suite to assure me. I can add to the test suite if I have a question, or want to lock in a behavior.

When it's a third party library, everyone assumes it's supposed to work? but when it's a system in the same repository, all of a sudden all bets are off, and you need to understand it fully to get anything done?

It's good when things just work and you can use an API, but most of the time you have to dig whatever is under the rug.

If most changes require simultaneously changing multiple areas of the code, such that changing one system implies changing every other system with roughly equal probability, then it's not well designed.

I don't know what else to tell you. It's going to be hard to iterate or maintain that system, in part because it requires a high cognitive load. None of the code in such a system provides any cognitive leverage. You can't rule out, or infer behavior of a large amount of code, by reading a small amount.

If such a system is important, then part of the strategy has to be to improve the architecture.

SickOfItAll• 11 months ago

It’s simple, but developers are generally terrible at it, especially the ones who are ‘smart’: Aim to think in terms of contracts and interfaces, not implementation. I don’t want to know what’s in your black box in order to understand how it works; if you make me read your code, you’ve done it wrong.

zmmmmm2• 11 months ago

If you are using small crisp API boundaries to break up the system, "smart developer quirks" don't really matter very much

To me this is the upside of the microservices concept. Of course, true microservices take it way too far. But once you tell two teams they can only talk to each other with APIs and make them use tooling that properly defines what those are (schemas etc) .... all of a sudden they are forced to draw those boundaries well and then stick to them. And they get really conservative about changing them and think hard about what the definitions should be up front. It's sort of perversely sticking technical friction in at the points where you want there to be natural conservatism around change.

hinkley7• 11 months ago

Cognitive load may be the dominant form of stress but it is not the only one. I feel like this is very close to correct but subtlety and critically broken.

In particular, when the shit hits the fan, your max cognitive load tanks. Something people who grumble at the amount of foolproofing I prefer often only discover in a crisis. Because they’re used to looking at something the way they look at it while sipping their second coffee of the day. Not when the servers are down and customers are calling angry.

You’ll note that we only see how the control room at NASA functions in movies and TV when there’s a massive crisis going on, or intrigue. Because the rest of the time it’s so fucking boring nobody would watch it.

zkmon• 11 months ago

Children were always told to cram as much as possible into their memory. It was even claimed that, more you put into memory, you mind works better.

Not quite. Human mind has evolved to interpret the sensory data collected by senses, and cause necessary action. Some of that interpretation uses memory to correlate the perceived data with the memory data. That's pretty much it.

Overloading the human memory with tons of data which is not related to the context in which the person lives, can cause negative effects. I suspect it can also cause faster aging. New experiences, new information is like scales on a tree trunk. As you accumulate more of it, you age more.

hinkley7• 11 months ago

I love learning and until recently despised teaching. I felt like a double agent nodding along at all the lies my teachers told me while I mastered the material almost in spite of the teaching instead of because of it. This became a real problem I college when the material was no longer a given. There were going to be people who flunked because the material was just too hard.

I have always been a C+ student of rote memorization at best. Almost enough to be good at trivia, but not enough to do well in coursework. I am always trying to build a Theory of a System from practically word one, which is the fifth stage of learning, where rote is the first.

scoofy• 11 months ago

I always explain it this way:

Balancing a cup on a tray isn't too hard. The skill comes in when you can balance 10 cups, and a tray on top of them, and then ten more cups, and another tray, and a vase on that... each step isn't difficult, but maintain the structure is difficult. It's like that, but with ideas.

stevage3• 11 months ago

A tip: if you're ever writing an article like this which is essentially do's and don'ts, adopt a consistent format for each. In many of these it's not immediately clear which is the do and which is the don't, creating, ironically, cognitive load for the reader.

xiphmont• 11 months ago

This is actually some wonderful work that succinctly explains a lot of my experience. Much of how I was formally taught to program is counterproductive to the big picture the second someone else has to understand the code. It's part of the reason that I hate dealing with Rust and C++, and breathe a sigh of relief when the codebase I need to suck into my head is good old C. C offers fewer ways to hide all the working code in six layers of templates.

zakirullin15• 11 months ago

Nice to hear that it resonates with your experience. I liked C for the exact same reason. Switched to Golang recently, simplicity is cherished here too!

ivanjermakov2• 11 months ago

Let's say we have been asked to make some fixes to a completely unfamiliar project.

How real is this use case? Unless you switch projects really often, this is like a week per two years.

Perhaps we should focus on solving problems that are hard by nature, not by experience of a developer or other external factors.

msephton• 11 months ago

Curious why github is linked and not the blog post? https://minds.md/zakirullin/cognitive

rkagerer• 11 months ago

These are good tips. A lot of it boils down to writing well-organized code geared for human consumption.

Junior programmers too often make the mistake of thinking the code they write is intended for consumption by the machine.

Coding is an exercise in communication. Either to your future self, or some other schmuck down the line who inherits your work.

When I practice the craft, I want to make sure years down the line when I inevitably need to crack the code back open again, I'll understand what's going on. When you solve a problem, create a framework, build a system... there's context you construct in your head as you work the project or needle out the shape of the solution. Strive to clearly convey intent (with a minimum of cognitive load), and where things get more complicated, make it as painless as possible for the next person to take the context that was in your head and reconstruct it in their own. Taking the patterns in your brain and recreating them in someone else's brain is in fact the essence of communication. In practice, this could mean including meaningful inline comments or accompanying documentation (eg. approach summary, drawings, flowcharts, state change diagrams, etc). Whatever means you have to efficiently achieve that aim. If it helps, think of yourself as a teacher trying to teach a student how your invention works.

ruszki• 11 months ago

As a coder, these are the exact problems which shouldn’t cause problems for you. You should be a coder because you’re better in these problems than others.

More coders are needed, than to who these are “simple”, I understand. But, if you have problems with these, I would definitely try to pivot to something else, like managerial positions. Especially with AI on us. Of course, if you are fine to be an “organic robot”, then it’s fine, but you’ll never really get why this profession is awesome. You’ll never have the leverage.

baazaa• 11 months ago

I would just add the IsAllowed etc. as a comment next to the relevant line. Often the explanation is bigger than what you'd want in a variable name, I find it less overhead than making more variables, and it makes better use of screen-space.

I'd only lean towards intermediate variables if a) there's lots of smaller conditionals being aggregated up into bigger conditionals which makes line-by-line comments insufficient or b) I'm reusing the same conditional a lot (this is mostly to draw the reader's attention to the fact that the condition is being re-used).

neehao• 11 months ago

This article covers a lot of the points: https://www.gojiberries.io/building-together-separately-chal...

"A single page on Doordash can make upward of 1000 gRPC calls (see the interview). For many engineers, upward of a thousand network calls nicely illustrate the chaos and inefficiency unleashed by microservices. Engineers implicitly diff 1000+ gRPC calls with the orders of magnitude fewer calls made by a system designed by an architect looking at the problem afresh today. A 1000+ gRPC calls also seem like a perfect recipe for blowing up latency. There are more items in the debit column. Microservices can also increase the costs of monitoring, debugging, and deployment (and hence cause greater downtime and worse performance)."

nige123• 11 months ago

Too much cognitive load is a flow stopper.

Finding flow while coding is a juggling act to keep things in the Goldilocks zone: not too hard, not too easy.

This is tricky on an individual level and even trickier for a team / project.

Coding is communicating how to solve a problem to yourself, your team, stakeholders and lastly the computer.

The Empathic Programmer?

bambax• 11 months ago

Cognitive load is an important concept in aviation. It is linked to the number of tasks to run and the number of parameters to monitor, but it can be greatly reduced by training. Things you know inside and out don't seem to consume as much working memory.

So in software development there may be an argument to always structure projects the same way. Standards are good — even when they're bad! because one of their main benefit is familiarity.

Szpadel• 11 months ago

I would say that's very important rule. We have lots of projects using framework dependent magic, lots of useless interfaces and factories that give only theoretical value, magic that patch other classes methods etcz but this is standard practice in this framework and all experienced developers know that.

by doing something better here would actually not bring any value, because it would mean that developers would have to remember that this one thing is done differently.

that's trap where I would say many mid Devs fall in, they learned how do things better, but increase congnitive load for the rest of developers just by doing things differently.

TZubiri3• 11 months ago

An important difference is that the aviator would be the user of the airplane system. OP is talking about the cognitive load of the plane engineer.

It's an important distinction in terms of priorities. I personally think the experience of the user is orders of magnitude more important than engineer cognitive load.

schnatterer• 11 months ago

business logic and http status codes Why hold this custom mapping in our working memory? It's better to abstract away your business details from the HTTP transfer protocol, and return self-descriptive codes directly in the response body: { "code": "jwt_has_expired" }

While the logic behind it sounds reasonable, REST does the exact opposite with the same goal: simplicity, easy to learn, i.e. reduce mental load. I know there are other reasons for REST/SOAP/Graphql, etc. Still makes mental load a somewhat subjective matter to me.

hn_throwaway_99• 11 months ago

In my experience, though, a lot of "REST in the real world" failed at its lofty original goals, precisely because its original goals required too much cognitive load.

The reason REST largely succeeded (or, rather, what I like to refer to as "REST-lite") is because people who wanted to build stuff quickly on the web realized "Hey, I don't need all this protocol complexity (see: SOAP), I can just make simple, human-readable API calls over the same HTTP layer my browser uses anyway".

There is other stuff in "official REST" that I think has some value, like the noun/verb structure of API routes, but shoehorning API-level error codes into HTTP status codes has been a disaster IMO. Every time I've seen this done I've seen the same issues come up again and again and new developers constantly have to rediscover solutions and problem spots. Does "404" mean the API endpoint doesn't exist, or that particular resource doesn't exist? How do I map my very specific API error to rather generic HTTP status codes? Does a status code error mean a problem with the networking or the application?

Too• 11 months ago

The article misses that http status code is not a custom mapping, it’s a standard mapping. Using this standard, most http libraries will already be equipped with features to handle them, for example automated retries and backoffs on a 429 with Retry-After.

Replacing this standard with custom strings in the response body is terrible advice. Even if we all could have wished that http status codes should have been human readable strings rather than numbers. Augmenting the standard response with additional custom information is still something you can and should do as cherry on the top, or if you have many conditions falling under the same standard code. Like, don’t shoehorn something custom into 418 I’m a teapot just because it happened to be unused.

asimovfan• 11 months ago

I don't seem to come across such limits when i am doing something i am not supposed to be doing (procrastinating, for example obsessively reading something other than what i should be reading).

0xbadcafebee• 11 months ago

We need something more fundamental, something that can't be wrong.

What is this bug in software people's brains that keeps thinking "I can come up with a perfect idea that is never wrong" ? Can a psychologist explain this to me please?

Like, scientists know this is dumb. The only way something can be perceived as right, scientifically, is if lots of people independently test an idea, over and over and over and over again, and get the same result. And even then, they just say it's true so far.

But software people over here like "If I spend 15 minutes thinking about an idea, I can come up with a fundamental principle of everything that is always true forever." And sadly the whole "fundamental principle" is based in ignorance. Somebody heard an interesting-sounding term, never actually learned what it meant, but decided to make up their own meaning for it, and find anything else in their sphere (software) that backs up their theory.

If they'd at least quoted any of the academic study and research about cognitive load over the past 35 years, maybe I might be blowing this out of proportion? But nope. This is literally just a clickbait rant, based on vibes, backed up by quotes from blogs. The author doesn't seem to understand cognitive load at all, and their descriptions of what it is, and what you should do in relation to it, are all wrong. The article doesn't even mention all three types of cognitive load. And one of the latest papers on the subject (Orru G., Longo L. (2019)) basically came to the conclusion that 1) the whole thing is very complex, and 2) all the previous research might be bunk or at least need brand new measurement methods, so... why is anyone taking this all as if it's fact?

But I'm not really bothered by the ignorance. It's the ego that kills me. The idea that these random people who know nothing about a subject are rushing to debate this, as if this idea, or these people's contributions, have merit, just because they think they're really smart.

jakubdudek• 11 months ago

Unless you have a quad-core brain like me and can vibecode four separate parts of the project in four terminal tabs. Of course, using your own method. Just kidding, of course.

gblargg• 11 months ago

"Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?" -- Brian Kernighan

defanor3• 11 months ago

I think most programmers agree that simpler solutions (generally matching "lower cognitive load") are preferred, but the disagreements start about which ones are simpler: often a lower cognitive load comes with approaches one is more used to, or familiar with; when the mental models one has match those in the code.

For instance, the article itself suggests to use early/premature returns, while they are sometimes compared to "goto", making the control flow less obvious/predictable (as paxcoder mentioned here). Intermediate variables, just as small functions, can easily complicate reading of the code (in the example from the article, one would have to look up what "isSecure" means, while "(condition4 && !condition5)" would have shown it at once, and an "is secure" comment could be used to assist skimming). As for HTTP codes, those are standardized and not dependent on the content, unlike custom JSON codes: most developers working with HTTP would recognize those without additional documentation. And it goes on and on: people view different things as good practices and being simpler, depending (at least in part) on their backgrounds. If one considers simplicity, perhaps it is best to also consider it as subjective, taking into account to whom it is supposed to look simple. I think sometimes we try to view "simple" as something more objective than "easy", but unless it is actually measured with something like Kolmogorov complexity, the objectivity does not seem to be there.

brucehoult2• 11 months ago

For instance, the article itself suggests to use early/premature returns

I like premature returns and think they reduce complexity, but as exclipy writes (I think quoting Ousterhout) 'complexity is defined as "how difficult is it to make changes to it"'.

If premature returns are the only premature exit your language has then they add complexity in that you can't then add code (in just one place) that is always executed before returning.

A good language will also have "break" from any block of code, such that the break can also carry a return value, AND the break can be from any number of nested blocks, which would generally mean that blocks can be labelled / named. And also of course that any block can have a return value.

So you don't actually need a distinguished "return" but only a "break" that can be from the main block of the function.

A nice way to do this is the "exit function", especially if the exit function is a first class value and can also exit from called functions. (of course they need to be in a nested scope or have the exit function passed to them somehow).

It is also nice to allow each block to have a "cleanup" section, so that adding an action to happen on every exit doesn't require wrapping the block in another block, but this is just a convenience, not a necessity.

Note that this is quite different to exception handling try / catch / finally (Java terms) though it can be used to implement exception handling.

derf_• 11 months ago

A good language will also have "break" from any block of code, such that the break can also carry a return value, AND the break can be from any number of nested blocks, which would generally mean that blocks can be labelled / named. And also of course that any block can have a return value.

Even in a language that is not "good" by your definition... you have basically just described a function. A wrapper function around a sub-function that has early returns does everything you want. I use this pattern in C all of the time.

neutronicus• 11 months ago

An old C/C++ argument lol. The C people want their exit blocks, the C++ people want to write destructors.

As a C++ guy I'm on the early-return side of things, because it communicates quickly which fallible operations (don't) have fallbacks.

You see "return" you know there is no "else".

Also, as a code-formatting bonus, you can chain a bunch of fallible operations without indenting the code halfway across your monitor.

mattmanser• 11 months ago

Personally I wouldn't agree with this. I've adopted a pattern where I try to only ever return the success value at the end of a function. Early returns of success value don't feel clear to me and make the code hard to read. I think that sort of code should only be used if you need high performance. But for clarity, it hurts.

Instead I think you should generally only use early returns for errors or a null result, then they're fine. Ditto if you're doing a result pattern, and return a result object, as long as the early return is not the success result (return error or validation errors or whatever with the result object).

So I feel code like this is confusing:

    function CalculateStep(value) {
       if(!value) return //fine

       ///a bunch of code
   
       //this early return is bad
       if(value < 200) {
          //a bunch more code
          return [ step1 ]
       }

       ///a bunch more code

       return [ ..steps ]
 
    }

The early return is easy to miss when scanning the code. This is much less confusing:

    function CalculateStep(value) {
       if(!value) return //fine

       ///a bunch of code
   
       let stepsResult : Step[]

       if(value < 200) {
          //a bunch more code
          stepsResult = [ step1 ]
       } else {
          //a bunch more code
          stepsResult = [ ..steps ]
       }

       //In statically typed languages the compiler will spot this and it's an unnecessary check
       if(!stepsResult) throw error

       //cleanup code here

       return stepsResult 
    }

It makes the control flow much more obvious to me. Also, in the 2nd pattern, you can always have your cleanup code after the control block.

lelanthran• 11 months ago

I prefer to have both single return and early return, like this: https://github.com/lelanthran/libds/blob/b5289f6437b30139d42...

whilenot-dev2• 11 months ago

one would have to look up what "isSecure" means, while "(condition4 && !condition5)" would have shown it at once

You would feel the need to look up a variable called isSecure, but would not need to look up condition4 or condition5? I think the point TFA was making is that one could read isSecure and assume what kind of implementation to expect, whereas with condition4 I wouldn't even know what to look for, or I'd even struggle to hold any assumption.

  /* this one needs to make sense in the end */
  isSecure = user.role == 'admin'
  
  /* these two do not */
  condition4 = user.id <= 4
  condition5 = session.licenseId == 5

> and an "is secure" comment could be used to assist skimming

Those are exactly the kind of comments I'd rather see written out as intermediate variables. Such comments are not explaining to you any of the Why?s anyway, and I also tend to trust the executing code much more than any non-type-related annotating code, as comments are rarely helpful and sometimes even describe wishful thinking by straight-up lying.

Intermediate variables assist in skimming too.

defanor3• 11 months ago

You would feel the need to look up a variable called isSecure, but would not need to look up condition4 or condition5?

I assume that those "conditions" are placeholders, not to be read literally in the example (since the example is not about poorly named variables, but about complex conditions), so I did not mean them literally, either. Supposedly those would be more informative names, such as "channel_encrypted", "checksum_verified".

[...] describe wishful thinking by straight-up lying

This was what I had in mind upon seeing that "isSecure" bit, too: could easily be a lie (or understood differently by different people). But taking a little more effort to check then, and/or having to remember what those variables actually mean. It is a commonly debatable topic though, where the good balance is, similarly to splitting code into small functions: people tend to balance between spaghetti code and extreme splitting.

My point though is not to argue with those particular points here, but that we have no such practices/rules universally considered simple and formally stated/verifiable.

dsego7• 11 months ago

isSecure = user.role == 'admin'

I would rather name intermediate variables to match the statement rather than some possible intent, it's basically a form of semantic compression. For example isAdminUser = user.role == 'admin' - here we are hiding away the use of roles which is not relevant for the conditional, but isSecure can mean anything, we don't want to hide the concept of being an admin user, just the details of using roles to determine that. At least that's my take.

wraptile• 11 months ago

This is a very popular pattern in python where you'd introduce _variable before the evalution so:

if (user.id < 4 and user.session): ...

# you'd do

_user_has_access = (user.id < 4 and user.session) if _user_has_access: ...

# or even walrus

if _user_has_access := (user.id < 4 and user.session): ...

One of my coworkers really liked this pattern and his code was always so easy to read and to this day I'm carrying this torch!

Cthulhu_• 11 months ago

Likewise, some people prefer ternary statements for short checks; I want to agree because ternaries are one of the first things you learn after if/else/while/for, but at the same time... they're a shorthand, and shorthand is short but not necessarily more readable.

For one-off things like value = condition ? a : b I don't mind much, but I will make an issue as soon as it spans more than one line or if it's nested.

mabster• 11 months ago

I particularly don't like ternaries with side-effects or control flow. In particular with control flow I prefer it always tabbed in otherwise sometimes I miss it -- if statements are much better for this.

davemp• 11 months ago

I prefer it as long as there’s no side effects. You get tighter semantics which I think helps readability (and I trust compilers to be able to handle it optimally). I find the following format to be very nice:

    value = (condition)
      ? foo
      : bar;

epolanski2• 11 months ago

Indeed, familiarity is 95% the reason why one would find a solution more, or less simple.

zakirullin15• 11 months ago

Cognitive load depends on the mental models one has, yes.

The problem is that familiarity is not the same as simplicity. They feel the same — that same ease of moving through a space without much mental effort — but for very different reasons. Every “clever” (read: “self-indulgent”) and non-idiomatic trick you use incurs a learning penalty for everyone else. Once they have done that learning, then they will find working with the code less difficult. So it is hard to recognise how to simplify code that you are already familiar with. This is why I try to get “the new kid” to critique the code before they get too institutionalised!

This was explored in the latter part of the article.

dsego7• 11 months ago

Sometimes an established pattern is easier to understand than the improved version. In that case convention is better, for example comparing http codes directly instead of giving them names, since those are easy to read for anyone who's ever done web dev.

mikepurvis2• 11 months ago

A lack of nuance about this kind of thing is part of what enrages me when ChatGPT tries to tell be a planned change or design is going to be “elegant” or “simple”. It’s like… maybe yes, maybe no, but those are not binary terms and throwing them around like that makes it sound like an enthusiastic intern sucking up to his sensei rather than a digital brain whose thoughts are formed by having ingested billions of lines of real life code.

lazylester• 11 months ago

your rage suggests that you think ChatGPT is making value judgements about elegance or simplicity. You surely know where it picked up those concepts don't you?

nurettin• 11 months ago

Unfortunately there is no one definition of simple, because developers call simple "whatever they are used to" rather than an objective measure such as "the least branching" or "the fewer lines of code".

The best I can come up with is "code that causes the least amount of scrolling" which is hard to measure and may be mitigated with IDE help.

PaulStatezny• 11 months ago

programmers agree that simpler solutions...are preferred, but the disagreements start about which ones are simpler

Low ego wins.

1. Given: The quality of a codebase as a whole is greatly affected by its level of consistency + cohesiveness

2. Therefore: The best codebases are created by groups that either (1) internally have similar taste or (2) are comprised of low ego people willing to bend their will to the established conventions of the codebase.

Obviously, this comes with caveats. (Objectively bad patterns do exist.) But in general:

Low-ego → Following existing conventions → They become familiar → They seem simpler

Sleaker• 11 months ago

I don't think this necessarily is accurate I've come into a lot of projects that no one understands well, but everyone continues to follow the same bad conventions that already exist which just adds to the problems. Ex: deep nesting, no early exit, deep object inheritance.. this happens because a lot of developers don't want to rock the boat, AND because they don't have the skills to unwind the complexity in a manageable amount of time without also causing serious problems.

shreddit• 11 months ago

Don't agree with "Business logic and HTTP status codes" tbh, because now i have to work with apis that do this:

Statuscode: 200 { success: false, error: "..." }

Culonavirus• 11 months ago

I don't really care either way, it's not a big issue to me, but I can see why people might do that. I mean what if an api endpoint returns a 403 when the end user doesn't have access to that resource, but also 403 because you, the consumer/app doesn't have access to the "server" the api is running on? HTTP codes were originally intended as server status codes, not server application status codes. At least with 200 you know your request was processed on the server successfully.

Izkata2• 11 months ago

Also, apache ignores the content body and returns an empty string with several classes of error codes, so using 200 is the only reliable way when you want to get that custom error message to the user.

ppsreejith• 11 months ago

A lot of comments mention John Ousterhout's book Philosophy of software design and it's definition of complexity of a system being cognitive load (I.e the number of disparate things one has to keep in mind when making a change). However IIRC from the book, complexity of a system = Cognitive load * Frequency of change.

The second component, frequency of change is equally important as when faced with tradeoffs, we can push high cognitive load to components edited less frequently (eg: lower down the stack) in exchange for lower cognitive load in the most frequently edited components.

hollowturtle• 11 months ago

Like another user said it depends on each developer background what's simpler and what's not. For example I have a problem with intermediate variables for improving readability, like isAllowed, it really is more readable but more often than not in large codebases what the name implies is not what the conditional check is or it is but it's not exaustive. So i have to inspect the variable to see what it actually is. The thing is that comments and variable names must be maintained as well as code, so it implies a certain degree of cognitive load to maintain. While a conditional like (condition2 || condition3) looks bad it still is more straightforward

austin-cheney• 11 months ago

People can argue about this all day, but one thing is always crystal clear.

Simplicity comes from practice writing and refactoring large code thousands of times. People with limited or shallow experience may think they are good at this but only when they isolate themselves to known patterns of comfort or some giant framework. There is a lot of insecurity there.

Super experienced people, that is people with lots of practice writing large original applications, don’t think like the pretenders. Simplicity is built in like muscle memory. They just solve fucking problem and go drink a beer. There is no memorized pattern nonsense.

The super experienced developers see the pretenders for what they are while the pretenders either can’t see the distinction or just feel hostility at the deviation far outside a memorized convention.

hackrmn• 11 months ago

In my experience, writing readable code and writing code that behaves correctly (fulfills the contract/requirements without hiding potential faults) is often mutually exclusive -- most people end up doing one or the other. This is related to the never-ending functional programming vs. "traditional programming" (a target in motion, largely OOP or in the very least "whatever is taught at the graduate schools"), since the former, in contrast to the article which pretty much _assumes_ the latter, doesn't even facilitate "variables", literally or in informal sense (things you can "assign to", whether changing or not).

Anyway, I happen to belong in the latter category according to most -- the longer I have been doing this, the more I lean into the purely functional style, almost mathematical vigor, because I have learned how much (or rather little) margin there is to introduce subtle errors once you have actual _variables_ that may change freely, which start to encourage you to do other things which in the end contribute to lack of correctness, readable or not.

Now, you may blame people like me, and I cannot blame you for not having the cognitive load capacity to understand some of the code I write "succinctly", but my point is that for all the merit of the article (yes, I agree code is read much more often than it is written, lending value to the "readability" argument), it doesn't acknowledge the fact readability and correctness are _in practice_ often mutually exclusive. Like, in the field. Because I wager that the tendency is to approach a more mathematical expression style as one becomes better at designing software, with adversarial conditions manifesting in terms of bugs hiding in mutability of state and large, if "simple", bodies of functions, classes (which have methods you cannot guarantee to not mutate the object's state).

We need to find means to write code that is readable but without compromising other factors like mutability which _too_ has been shown to compromise correctness. What good is readable software that never manages to escape the vortex of issues, driving the perpetually busy industry "fixing bugs".

At my place of work, I obviously see both kinds of the "mutually exclusive", and I can tell you without due pride and yet with good confidence, people who write readable code -- consisting of aliasing otherwise complex expression with eloquently named variables (or sometimes even "constants", bless their heart), and designing clumsy class hierarchies -- spend a lot of subsequent effort never being able to be "done" with the code, and I don't mean just because requirements keep changing, no -- they sit and essentially "fixup commit" to the code they write, in perpetuity, seemingly. And we have select few who'd write a code-base with as few variables as possible, with a lot of pure function -- what I referred to as "mathematical programming" in a way -- and I never hear from them much offering "PRs" to fix their earlier mishaps. The message that sends me is pretty clear.

So yeah, by all means, let's find ways to write code our fellow man can understand, but the article glosses over a factor that is at least as important -- all the mutability and care for "cognitive load" capacity (which _may be_ lower for current generation of software engineers vs earlier ones) may be keeping us in the rotating vortex of bugs we so "proudly" crouch over as we pretend we are "busy". I, for one, prefer to write code that works right from get-go, and not have to come back to said code unless the requirements which made me write it the way I did, change. On a very rare occasion, admittedly, I have to sacrifice readability for correctness, not because it's inherently one or the other, but because I too haven't yet found the perfect means to always have both, and yet correctness is on the absolute top of my list, and I advocate that it should be on top of your as well, dare I to say so. But that is me -- perhaps I set the bar too high?

ksec• 11 months ago

I think this just describe why people procrastinate.

itsafarqueue• 11 months ago

Don’t bother with this if you want to get promoted. Others have discussed this in thread and are right. If you build beautiful, simplified abstractions, your skill will be taken for granted as these interfaces appear obvious once discovered (by virtue of their proximity to truth, incredibly difficult to create, easy to verify). If you are in even a reasonably large org, go the other way. Be an Architecture astronaut. Build complex, clever stuff that is deliberately high cognitive load. Get your bus-factor as close to one as possible. Go the other way only if your comp is directly tied to company performance.

ttz4• 11 months ago

It hurts because it's true

The amount of staffs at my place who build pointlessly complex bullshit that doesn't actually do anything different is too damn high

baalimago2• 11 months ago

The same principle applies within context engineering

mleonhard• 11 months ago

There is no “simplifying force” acting on the code base other than deliberate choices that you make. Simplifying takes effort, and people are too often in a hurry.

There is a simplifying force: the engineers on the project who care about long-term productivity. Work to simplify the code is rarely tracked or rewarded, which is a problem across our industry. Most codebases I've worked in had some large low-hanging-fruit for increasing team productivity, but it's hard to show the impact of that work so it never gets done.

We need an objective metric of codebase cognitive complexity. Then folks can take credit for making the number go down.

baalimago2• 11 months ago

Hey, OP, stop bashing on functional languages..!

about3fitty• 11 months ago

Cognitive load is super important and should be optimised for. We all should have as our primary objective the taming of complexity.

I was surprised to find an anti-framework, anti-layering perspective here. The author makes good points: it’s costly to learn a framework, costly to break out of its established patterns, and costly when we tightly couple to a framework’s internals.

But the opposite is also true. Learning a framework may help speed up development overall, with developers leaning on previous work. Well designed frameworks make things easy to migrate, if they are expressive enough and well abstracted. Frameworks prevent bad and non-idiomatic design choices and make things clear to any new coder who is familiar with the framework. They prevent a lot of glue, bad abstractions, cleverness, and non-performant code.

Layering has an indirection cost which did not appeal to me at all as a less experienced developer, but I’ve learnt to appreciate a little layering because it helps make predictable where to look to find the source of a bug. I find it saves time because the system has predictable places for business logic, serialisation, data models, etc.

nathane2802• 11 months ago

brb adding this to my CLAUDE.md

nathane2802• 11 months ago

For the lazy:

### Reduce Cognitive Load By:

*1. Simplify Conditionals*

``` // High cognitive load if val > someConstant && (condition2 || condition3) && (condition4 && !condition5)

// Low cognitive load isValid = val > someConstant isAllowed = condition2 || condition3 isSecure = condition4 && !condition5 if isValid && isAllowed && isSecure ```

*2. Use Early Returns*

``` // Nested ifs if isValid { if isSecure { doStuff() } }

// Early returns if !isValid { return } if !isSecure { return } doStuff() // Happy path is clear ```

*3. Prefer Deep Modules*

- *Deep module*: Simple interface, complex implementation (e.g., UNIX I/O with 5 methods) - *Shallow module*: Complex interface for simple functionality - Few deep classes > Many shallow classes

*4. Use Self-Describing Values*

``` // Numeric codes requiring mental mapping 401 // expired token? 403 // insufficient access?

// Self-describing { "code": "jwt_has_expired" } ```

*5. Apply DRY Carefully*

- Don't create abstractions too early - Avoid tight coupling between unrelated components

### Avoid These Anti-Patterns:

*1. Inheritance Chains*

``` AdminController extends UserController extends GuestController extends BaseController Use composition instead ```

*2. Too Many Layers*

- Unnecessary abstraction layers add indirection, not simplicity - Only add abstractions when you need actual need to

*3. Framework Magic*

- Keep business logic framework-agnostic - Use frameworks as libraries, not containers for your logic - New developers shouldn't need months to learn framework "magic"

diegobit• 11 months ago

I think these books and resources should not be viewed as hard rules, but as sets of examples explaining guiding principles, and the internet is full of discussions that turn into religious wars over it.

It is always worth it for a programmer to dwell over what complexity is according to Osterhaur; it is worth it to reason over what Uncle Bob thinks is "clean" code, etc. I'm not benefiting from either by applying what they say dogmatically, but I improve my taste in what is good software to me, by discovering and trying many approaches. Without reading them I might never even have thought at a particular solution, or a particular frame of mind.

artur_makly• 11 months ago

Is it possible to have a system prompt for an LLM to follow some of these best practices? Has anyone made a reduced system prompt with these principles?

Cognitive load is what matters

Related Stories