Yellow
Yellow
YELLOW
Principles (or useless aphorisms) for software dev
Baldur Bjarnason
© 2023 Baldur Bjarnason
All rights reserved
Published in Hveragerði, Iceland
Typeset in the Literata typeface
CONTENTS
YELLOW........................................................................................... 6
1. Introduction .......................................................................... 9
2. Fear is a signal ....................................................................... 13
3. Just-in-time research ............................................................. 17
4. Technology changes slower than you think ............................... 21
5. Always maximise your understanding ..................................... 25
6. Gall’s Law ............................................................................ 29
7. Analogue ............................................................................. 33
8. Don’t tinker ......................................................................... 37
9. Correct and incorrect ............................................................. 41
10. Loose coupling ..................................................................... 45
11. Widely used standards........................................................... 49
12. Premature optimisation ........................................................ 53
13. Avoid state management ........................................................ 57
14. UX bugs versus complexity ..................................................... 61
15. The two questions ................................................................. 65
16. Don’t try to solve every problem ............................................. 69
17. Throwaway prototypes .......................................................... 73
18. Don’t be a correctness bully.................................................... 77
19. Worse is better, but it’s also how we got into this mess ................ 81
20. Yellow ................................................................................. 87
YELLOW
INTRODUCTION
Introduction
10
Yellow
11
FEAR IS A SIGNAL
Fear is a signal
14
Yellow
15
Fear is a signal
16
JUST-IN-TIME
RESEARCH
Just-in-time research
Just-in-time research will always beat trying to keep up with the web
development or the software development news treadmill.
This is a mistake I keep doing or have kept doing throughout my ca‐
reer, but I’m not a lone in that. It seems to be the norm in the industry.
We follow everybody who seems to know anything on social media;
we follow all the websites; we keep up with all the aggregators; we
overwhelm ourselves with noise every single day; and we keep trying
to remember all the little details and nuggets and new APIs and func‐
tion signatures.
Who is genuinely going to remember the exact way an object, a
standard API is constructed or how a standard function that comes
with a platform is called?
Our memory is fallible, it’s just how humans operate.
It might work as a tactic when you’re in your early 20s and your
memory is at peak efficiency but as you continue to age and your
memory degrades you will feel a deterioration in your abilities, be‐
cause you’ve built your entire method of working on something that is
not going to work forever.
It’s not sustainable in any way.
The only realistic alternative, the only option we all have if you
want to have a long-term career and not just give up once we reach our
30s or 40s is to just do the research just in time as you need it.
If you are making a web form, then that’s the time to look into the
form APIs.
18
Yellow
If you’re starting to work on an app, then that’s the time for you to
sit down and do research into the specific needs of that application.
Then you apply what you’ve just recently learned while it’s fresh in
your memory. Using something shortly after you’ve first encountered
it helps integrate it, and you’re much more likely to remember it that
way.
Things you use are much more likely to stick in your mind.
If you apply information while it’s still fresh in your mind you will
almost certainly remember it.
You might not even remember it as a fact.
It might not even go into your semantic memory of information
and content nuggets or trivia.
It might just end up as muscle memory. As something you end up
typing automatically without thinking about it.
That’s the best kind of learning when you’re working because it’s
something you don’t have to think about. You don’t have to recall. It
becomes almost like a mechanized feature like a snippet that you’ve
got built into your code editor.
Emphasize just-in-time research.
Try to read and learn things just before you actually use them be‐
cause then you’re much more likely to remember them, and then
you’re much more likely to integrate them into just the basic way of
how you work.
If you keep trying to follow everything, follow every update, every
new feature, every feature in development, every proposed specifica‐
tion, you will get overwhelmed.
You’ll get burnt out, and you will just have to give up.
It will not work.
It is not a strategy that will give you a long and healthy career.
Learning – proper learning – which involves a cycle of reading, us‐
ing and integrating, is the only way.
It’s the only sustainable way.
The rest is just fashion, just pop culture.
If you do follow all of the updates, the discourse, the news items as
entertainment, as the kind of gossip that you follow the same way you
19
Just-in-time research
follow celebrity news or even like they did with the old days of Valley‐
wag.
If you think of it as entertaining industry gossip, then yeah, that’s
fine.
That’s entertainment.
You don’t expect yourself to remember who slept with who while
shooting a movie 10 years ago.
You shouldn’t expect yourself to remember a random detail of a
specification that was proposed but never implemented five years ago.
Read as you need it, use it, and then you’re more likely to remem‐
ber.
20
TECHNOLOGY
CHANGES SLOWER
THAN YOU THINK
Technology changes slower than you think
22
Yellow
And this applies even more on the sort of granular level that we
work on in terms of software development.
We keep hearing about updates, about API changes, new features,
and new standards, but quite a few of these don’t actually ship, espe‐
cially on the web.
But more importantly, most of the noise that we hear is repetitive.
We hear about a proposal, and we hear about the change to the pro‐
posal.
We hear about another change to the proposal.
We hear about an alteration, about an update.
Our minds interpret it as a series of changes, when what actually
ships and is usable is just one thing. We’ve turned a single shipping
change that would be easy for us to follow into a noisy stream of up‐
dates that we can’t handle.
If you step back and follow just the aspects of these news updates
that you’re likely to be able to use in a software development project,
none of it actually happened in a real way.
Until it ships, it’s gossip.
Until it ships to enough people to make it usable, it’s gossip.
You don’t have to follow news about it
It doesn’t really matter because the feature might not actually ever
get enough of a critical mass of users for you to ever be able to rely on
it.
Much of the software development space is operating at a much
slower pace, a human pace, that we can actually step back and have
the luxury of waiting for.
We have the luxury to wait and see if something gets adopted by
people.
And that’s a human-scale time thing, if you pardon the word mess.
That’s not happening at the light speed everybody says tech oper‐
ates at.
Most of the concrete changes that you actually have to pay atten‐
tion to happen at a human scale, at a human pace, that matches our
own pace, that matches your or mine.
It’s not as much of a struggle for us to keep up with that.
23
Technology changes slower than you think
24
ALWAYS MAXIMISE
YOUR
UNDERSTANDING
Always maximise your understanding
26
Yellow
27
Always maximise your understanding
28
GALL’S LAW
Gall’s Law
30
Yellow
I have never seen anybody manage to break John Gall’s Law. It ap‐
plies to every single aspect of software development, in that we are
fond of planning and organising and building complex systems from
scratch. We design these intricate structures of objects and classes that
interact. We build things that have no chance ever of working.
Instead, the alternative that I always advocate is to try to bake evol‐
ution into your design. It’s fine to have a complex system design that
you’re aiming for in the long term, but you need to have a clear idea of
how it will evolve from a simple system that works to a complex sys‐
tem that works.
You cannot leap straight into the complex system.
You have to start small.
This applies to every system and subsystem in a software develop‐
ment project, whether it’s a feature or a module or the app itself.
Start with a single system, simple one that works, then you evolve
and add to it. If you’re adding a new feature, then it has to be a simple,
single thing that works from the beginning, and then you build from
there.
If you’re making an app, make a simple, bare bones, flawed but
working app. It can be flawed in that parts of it are obviously missing.
It can be flawed in that it’s ugly.
But the systematic aspect of it, the code, that needs to be working,
and it needs to be simple.
This is the only way to make working software, but it’s also a rarity.
It’s the exception. I have almost never been able to convince a man‐
ager that we should do it.
I’ve convinced them that they should do this, but they’ve never ac‐
tually accepted it in practice.
They say, yeah, absolutely.
I believe in a minimum viable product.
But then they keep adding things to what constitutes the minim‐
um, and they don’t realise that MVP is not the simple system that John
Gall is talking about.
The simple system does not have to be shipped.
31
Gall’s Law
It just has to exist as the foundation that you build on. But they
don’t really get that when they’re managing the project.
In the story, feature, or point breakdowns I’ve seen, it’s clear they
don’t understand the systematic aspect of it.
They almost always start with this vision of a complex interlocking
thing we’re just colouring in the numbers for.
They don’t grow the system.
They don’t grow the software.
There are exceptions, and those are great projects and great places
to work in.
But all too often, there’s a fundamental misunderstanding of how a
software system works on the part of the managers or the executives
of the projects that I’ve worked on.
I suspect that the same applies to everybody who’s listening to this.
32
ANALOGUE
Analogue
34
Yellow
35
Analogue
Even the stuff that you love because, gee whiz, it’s such an innovat‐
ive example of CRDTs or Operational Transformation or some techno‐
logical whiz-bang thing.
The actual benefit it provides to people who use it is probably much,
much less than the joy of novelty is giving you.
36
DON’T TINKER
Don’t tinker
Don’t tinker.
Tinkering is endemic to, well, businesses everywhere, in that we
make a decision, we see the results, then we change what we did and
see another result. Repeat until you’ve got a mess.
What’s happening when we do that, generally speaking, is the first
decision had a margin of error: the role that randomness, environ‐
ment, and systemic variation played in the result.
Then we look at that result and assume that it was somewhat de‐
terministic or more deterministic than it was, but our change expands
the margin of error. We add the margin of error of the new experi‐
ment – our change – to the margin of error of the first experiment.
We’re even further away from understanding what was happening in
the first experiment.
The margin of error expands because we don’t know in which direc‐
tion any of it is swinging.
What we’re doing when we tinker with a system, when we tinker
with a project and update it as we do, is we are increasing the random‐
ness and obfuscating the facts.
We are blinding ourselves to what’s actually happening. We’re
blinding ourselves with noise.
The common way to counteract this is with A/B tests.
Those don’t really work either.
When done correctly, they are useful for establishing a local max‐
ima. That is, from the starting point, the sort of local optimum for
38
Yellow
39
Don’t tinker
formation because we then can account for that margin of error and
see what that introduces to the rest of the system.
But tinkering blindly, which is most of what we do, most of what
every manager I’ve ever worked with does, just makes you less aware
of what’s happening.
It’s no wonder – it isn’t a surprise that the end result is most soft‐
ware companies and most software projects are just failures. Because
throughout the project, the people who are supposed to minimise
variation and minimise randomness are actually just steadily increas‐
ing the noise levels and increasing the margin of error in all of our
data and measurements.
That’s no way to run an industry, but it happens to be the way we do
run ours.
40
CORRECT AND
INCORRECT
Correct and incorrect
If it’s at all possible, you should try to make sure that incorrect looks
different from correct.
This might sound obvious, but it’s generally not the practice. You
can see this pretty much throughout the software industry.
You have forms where invalid entries are basically indistinguish‐
able from valid until the absolute worst moment, when the user has
filled in the entire form and is about to submit it.
Our training material and education and documentation displays
incorrect examples, and they look identical to the correct examples,
and our memories aren’t perfect, they’re going to remember them
both.
Our minds are pattern matchers.
If the wrong thing looks exactly like the right thing, it’s going to
confuse us. If you in your training material keep showing how not to
code for a specific API, how not to use a specific function, as well as
how to use it, there’s a very good chance that what the reader is taking
away from it is the incorrect way.
That’s the way that they’ll remember when it actually comes to
working and using what you’ve told them.
And this is almost universal in our industry.
We take away all the signals that are supposed to help people.
We mix the wrong thing and the right thing and the errors and the
successful actions. It all looks the same, and it all looks like a muddle.
It all ends up being incredibly confusing for everybody involved: the
42
Yellow
end user, the software developer, the designer, the manager. We tend
to exist in a perpetual state of confusion.
The way we design our information space plays a big part of it.
We seem to be fine with it.
That’s the weird part.
It doesn’t seem to stop us.
43
LOOSE COUPLING
Loose coupling
46
Yellow
47
Loose coupling
48
WIDELY USED
STANDARDS
Widely used standards
50
Yellow
51
Widely used standards
fashion trends that people claim will be standard practice in the fu‐
ture.
Wait until it’s an actually widely used convention or a widely used
standard.
Until it is, ignore it and use something else.
52
PREMATURE
OPTIMISATION
Premature optimisation
54
Yellow
55
AVOID STATE
MANAGEMENT
Avoid state management
Avoid managing state as much as you can, no matter what kind of soft‐
ware you’re making.
There’s a reason why the one universally applicable debugging or
problem-solving tool in software and computing is turning it off and
on again.
That’s because of state, in that we are incredibly bad at managing
state in our software and our code.
It clutters up, it gathers, it sort of grows like mould here and there.
Much of the time we might not even be aware that we’re letting a com‐
ponent build up state. Then it starts to go wrong because it interacts
with other components in ways that we just have no way of under‐
standing.
This is why we’re told we should always avoid side effects.
As in, if you’re writing a function, that function should not do any‐
thing except return data.
It should not modify its input, it should not modify global state.
It should just do something with its input and return data – return a
value based on what it’s called with.
The same applies to object-oriented programming.
A method should only modify the object it’s called on. The object
being the value or the data that’s effectively being “returned”.
This is state avoidance, and it’s absolutely necessary if we are to try
and make stable software. We are just not good at keeping to that rule.
58
Yellow
59
UX BUGS VERSUS
COMPLEXITY
UX bugs versus complexity
Bugs hurt the user experience more than complexity helps it.
What I mean with this is we need to think of the end user and the
software they’re using to do their job as an interlocking system.
They are working in concert to accomplish a task.
Back in the olden days, back in the early days of Mac Classic or in
the early days of Windows, of Office in the 90s, they actually measured
this as a whole, measured this as task completion, as, you know, the
user and software working in concert.
But we stopped doing that. Instead, we began to A/B test individual
features and lost sight of what the overall goal is for the end user, why
they are actually hiring this software for a job.
There’s a diminishing return on investment on added complexity
from the end user’s perspective.
The more complex the interface becomes, the more effort they have
to put in to get the same rewards that they used to when the interface
was simpler.
The complexity we introduce also causes bugs. Software develop‐
ment is generally bad at what it does as an industry: we keep increas‐
ing the complexity, which adds bugs, and those bugs are more harmful
on the whole than the benefit the end user gets from the added fea‐
tures. Complexity does not outweigh the harm that comes from the
bugs because the bugs are everywhere.
They are all over the place. If you have ever done studies where you
are on location, and you’re watching somebody in an office environ‐
62
Yellow
ment or try to buy something online – if you’re doing the kind of re‐
search that used to be the norm, you will notice that every single one
of these interfaces is just filled with bugs.
Users keep having to redo things.
They keep having to correct for errors.
These bugs are not just software flaws or software defects.
The defects in the user interface are bugs from the perspective of
the end user.
And because that’s the person who we’re supposed to serve, it
should also be a bug from our perspective.
Complex interfaces are just a breeding environment for user exper‐
ience and user interface bugs.
It’s also a breeding environment for regular old software defects.
That’s what complexity does to a project.
Bugs tend to lose people, cost you money, lose work and destroy
data.
But, from the perspective of the end user, it’s primarily a way of
making things harder, less accurate, slower.
This is the industry we’ve become.
We have become an industry that values complexity and features at
the expense of the end user, because we trust that they will buy – that
their manager or their sales department will buy the software – des‐
pite the fact that it works less well than earlier or simpler versions of
the software.
We can try to counteract it by simply keeping this in mind:
Complexity harms the end user.
The reason is that the bugs that complexity causes harm the user
experience more than the added features tend to.
If you keep that in mind, you’re usually in a better place to serve
the end user and create good software.
Although I do recognize that getting that past management is of‐
ten, shall we say, tricky.
63
THE TWO
QUESTIONS
The two questions
66
Yellow
You both end up doing more work than you needed to do on the
component itself, and then you do more work than you needed to do
in writing the test afterwards. Then, because everything becomes
more complicated, you build up more bugs, more flaws, more com‐
plexity, there’s more need for documentation, there’s more need for
testing, there’s more need for quality assurance afterwards, you need
more end-to-end tests because the thing is bigger and more complex.
Test-driven development cuts through that. It is the simplest
strategy available to us for answering the core questions of software
development and generally speaking if somebody hands you a simple
solution to a complex problem, you take it.
It doesn’t matter if you have qualms about it or might have a heart‐
felt belief that somewhere out there, there might be a better solution
to the problem of software development. This is the best solution we
have, and it’s generally irresponsible to ignore that.
67
DON’T TRY TO SOLVE
EVERY PROBLEM
Don’t try to solve every problem
Absolutely do not try to solve every problem you can think of before
you really have to.
This ties in with the whole test-driven development thing. The test
defines the task you need to do, and you only do that task.
If there is a problem that comes up in the project or a bug, then you
write a test for that bug, and you write code that solves just that test.
A pitfall we all fall into is we tend to try and imagine all the possible
things that we might need, or the project might need – the future fea‐
tures we’ll need to add or integrate – and we tend to want to prepare
for this right at the beginning.
This doesn’t just add to our work. It does that too. It adds a massive
amount of work. If you look at the ratio of wasted work to actually
generally productive work in most software projects, it’s not going to
be as favourable as you’d like, because we keep solving problems we do
not have.
But this is also an issue because it leads us to build complex systems
from scratch. If you’ve paid any attention to Gall’s Law, you know
that’s not going to end well.
We keep imagining complex problems we don’t have yet, and we
keep designing complex solutions to those complex problems, which
require complex systems, and it leads us to just make something that’s
broken right out of the gate. This is why an effort to try and create
something more robust, something more reliable, often backfires.
We’ve created a complexity hell that is more broken.
70
Yellow
71
THROWAWAY
PROTOTYPES
Throwaway prototypes
74
Yellow
You need the ability to throw away that code, that code that was
done as an exploratory effort, as a potentially misguided experiment.
Parts of it told you that this is not something you should have done.
Other parts of it told you that there are better ways to do this. That
might have worked for the prototype, but there are better ways to do
it. And you see that now.
You need the freedom and the ability to be able to throw away pro‐
totypes. To do work that results in code that gets discarded.
If your team and your organization is to be able to ship ambitious
projects and ambitious products, you need the right to dispose of code.
If you don’t have that, if you’re working for an organization that
just does not let you throw away prototypes, and it demands that
everything you work on has to be towards software that ships, if they
don’t give you the space to do that learning, then you have to, if you
want to be able to do a good job or do a job, one that does not result in
software that’s buggy and crashes and collapses over time, you have to
talk them out of it.
You have to talk them out of their ambitions.
Or convince them to let you discard prototypes.
Either way, if you’re asked to do an ambitious project without the
ability to just throw away work, because it’s the learning that matters,
then you’ve been put in an impossible position.
You have been put in a position where you are not able to do your
job. That’s untenable. That’s not something any of us should accept.
We put up with a lot in software development. We put up with so
much nonsense. We put up with expectations that are completely dis‐
connected from reality. We put up with scenarios that are just wildly,
wildly unlikely to ever be possible. We are given budgets we know are
just fabrications.
But we have to draw the line somewhere. And we need to try at least
somewhere to draw the line and say, what you’re asking me to is just not
possible. It’s not realistic. And try to walk them back.
Or, you know, try to convince them to let you prototype. Let you do
experiments. Because that’s actually how you make ambitious things
happen. The return on investment on ambitious things tends to be
75
Throwaway prototypes
higher than just always going with the most conservative risk-free ap‐
proach.
If you really want to bet, make big bets and have big rewards, you
need ambition. And for that you need to be able to prototype.
That’s just a hard requirement.
76
DON’T BE A
CORRECTNESS BULLY
Don’t be a correctness bully
78
Yellow
79
Don’t be a correctness bully
80
WORSE IS BETTER,
BUT IT’S ALSO HOW
WE GOT INTO THIS
MESS
Worse is better, but it’s also how we got into this mess
82
Yellow
83
Worse is better, but it’s also how we got into this mess
84
Yellow
But the defects are still there, and they’re still accumulating, and
we’ve coasted for the past decades on the fact that the improvements
are collecting faster than the defects.
Occasionally, for some software systems, you actually get the op‐
portunity to stop and pause and try and fix some of the defects.
But you can never get rid of them all because “let defects ship” is
baked into how the entire industry works.
We’re working in a compromise system, and we need to be aware of
that because otherwise the trash we ship gets even more trashy.
There’s nothing we can do to truly fix it.
Not in this lifetime.
We’d have to invent an alternate timeline. Where we made different
choices 50 years ago and decided to prioritize correctness. Where the
software we’re using is much less capable than the software we have
today, but has fewer flaws, is easier to use, and doesn’t have the near-
singularity, black-hole-singularity levels of defects that our current
system has.
But that world doesn’t exist.
We have to live in this one.
Even if it’s disappointing, occasionally.
When you get up in the morning and see yet another bug report.
It’s the job.
85
YELLOW
Yellow
At the start of this project, I talked about the title, Yellow, and its in‐
spiration, Derek Jarman’s Blue, how that was born out of his illness.
I spoke about the fact that his motivation, his drive for his film was
much grimmer than for my simple project.
But there’s still a side to this that’s less uplifting.
Over the past year I’ve been pushing out books, projects, and art‐
icles. I released the book Out of The Software Crisis in November a year
ago. So, just over a year has passed since I began this push.
After that, I released another ebook. I’ve done more talks in the
past year than I’ve done in recent years. I’ve been pushing, writing
more, publishing more, and much of it comes from fear.
The same fear I said earlier on should only be thought of as a signal
and should not be something you let control you.
But I’ve been yellow. I’ve been letting this fear control me.
Over a year ago this summer, last year, I managed to catch COVID
for the first time.
I’ve been good at avoiding it, masking and everything, but my dad
caught it during a hospital appointment, and then I caught it from
him.
The illness itself was fine. It was just a flu-like thing. The problems
came afterwards.
For six weeks, my brain just wasn’t working. My memory was aw‐
ful. I had no way of focusing. My mind wasn’t my own any more.
88
Yellow
It meant I couldn’t work for six weeks. It cost me both time and
money. It affected my relationship with the people who’d hired me as a
consultant. It probably cost me that project in the long term.
But it frightened me in other ways as well.
About halfway through I could feel myself getting better. I was able
to start working again six weeks in. But it took more than six months
for me to sort of get back to the level I used to in terms of being able to
think and remember and structure my own thoughts. I’m still not
100%, even a year later.
This might sound surprising. That means that I wrote my first book
in a deep haze of COVID fog, where I frantically wrote what I could in
the between moments where I felt lucid and otherwise tried to focus
on working the easier tasks of editing and typesetting. Not that I want
to downplay the magnificent work that proper typographers do. I felt
that that was easier for me to focus on in that context.
I was driven by fear because I’ve seen this kind of change happen
well before COVID. One of the running ailments you notice if you look
through my family tree is vascular dementia.
Now, that goes hand in hand with lifestyle. There are people in my
family tree who drink, who don’t exercise, who eat loads of fatty
foods.
Many of them suffered from vascular dementia, sometimes from a
frighteningly early age.
So just by having the correct lifestyle and exercising, I had figured I
should be fine. I mean, it reduces the odds enough that I should be
fine.
But, you know, the possibility is always there in your mind, at the
back of your mind.
And that meant I have a certain awareness of what dementia looks
like.
And COVID felt like that.
It really felt like the same sort of chipping away at the ability to re‐
call, at the ability to hold focused thoughts and structure arguments,
felt like the same kind of deterioration that I saw in my granddad.
89
Yellow
So I’ve been pretty terrified for the past, what have you, year or so,
driven by fear in that – not really of the dementia, but just of this
awareness that the mind is a fragile thing.
It can be taken away at a moment’s notice.
But I’ve also been driven by the fact that low odds – having lowered
odds through better exercise and a more constructive lifestyle – is still
not zero.
This is always going to be a possibility going forward.
I got a preview of a possible future.
So I’m yellow. I’m full of fear.
It drove me to try and write a book to capture my opinions and my
thoughts on software development.
It’s what drove me to try and give people warning about the busi‐
ness risks that “AI” or generative “AI” had in the long term.
It’s what drove me to the research projects I’ve been trying to do
and trying to pull together this year.
And it’s what drove this project.
It’s looking at the way Jarman, the dying director, solved his prob‐
lem, which was, you know, more imminent, much more imminent
than hopefully something that might happen to me in a few decades.
Fingers crossed.
But his way of just using a blue screen with audio – that’s a way of
cutting corners, while still being expressive about it.
So this project was born, or reborn, because I’ve been actually
working on this for a while.
The first draft of these principles were written last spring, several
months ago.
I’ve been working on them since. Trying to sort of whittle them
down, hone them, and pick and choose.
But I always had this worry about how – how can I get this out in a
way that’s accessible but also quick?
Because, as I said, I’m frightened.
I’m worried that I want to maximize how… I want to use the time
that I have as well as I can.
Like I said, I don’t expect to be struck down anytime soon.
90
Yellow
91