The one book I insist my new hires read before starting is Edward de Bono’s “Simplicity”.
It suggests that we should value others’ time over our own. Every hour we spend making things simple gives a net benefit to humanity. Whether it is laws, industrial design, software, or documentation – our goal should be to make things radically simple.
Not only does simplicity save time – it also saves us from making catastrophic mistakes. Many recent Internet security issues are a direct result of complicated code implementing complicated standards. HeartBleed, for example, was partly caused by needless complexity.
The fundamental reason they all failed to find the vulnerability is that the OpenSSL code is extremely complex; it includes multiple levels of indirection and other issues that simply exceeded these tools’ abilities to find the vulnerability. Developers should simplify the code (e.g., through refactoring) to make it easier for tools and humans to analyze the program
The fact that it is so difficult to even determine what the allocator does is testimony that the memory allocation system itself is too complex!
How to Prevent the next Heartbleed – David A. Wheeler
Why do some people and institutions seem to thrive on creating increasingly complex standards and implementations?
It is, so I’m told by those with greater emotional empathy than I, impolite to call people “idiots”. So it would seem that those who write Internet standards have settled on the preferred adjective of “baroque“.
After many years of debate, as a result of the perceived need to accommodate certain DNS implementations that apparently couldn’t handle any character that’s not a letter, digit, or hyphen (and apparently never would be updated to remedy this limitation), the Unicast DNS community settled on an extremely baroque encoding called “Punycode” [RFC3492].
Punycode is a remarkably ingenious encoding solution, but it is complicated, hard to understand, and hard to implement, using sophisticated techniques including insertion unsort coding, generalized variable-length integers, and bias adaptation.
RFC 6762, Appendix F. emphases added.
Baroque is the fiddly, intricate, majestic, and fiendishly complicated form of art which sounds like this:
Complexity causes confusion. Confusion robs people of their time – although it can occasionally be amusing.
We need to stop confusion. We need to make things simple enough for people to understand without requiring them to go through the painfully humiliating ritual of screwing up the basics and asking for help.
Let’s take as an example HTML5 video and responsive images.
If you want to embed a video into your HTML, this is the simplest way to do so:
<video src="video.webm"> </video>
Suppose you want different video formats, there’s a relatively simple way to do that – specify the filename and (optionally) the codec within the file.
<video> <source src="video.webm" type='video/webm;codecs="vp8, vorbis"'/> <source src="video.mp4" type='video/mp4;codecs="avc1.42E01E, mp4a.40.2"'/> </video>
I say “optionally” because video standards are not quite as well established as image standards. While a JPG or PNG image can almost certainly be decoded by any computer, an MP4 could contain all manner of bizarre audio and video content.
Moving on to Responsive Images. This allows us to specify different sized images which the browser can pick from, depending on its resolution.
For a normal image, we can simple write:
<img src="picture.jpg" />
So, for a responsive image, following on from the previous example, we should be able to use something like this, right?
<img> <source src="pic.jpg" scale='1x'/> <source src="bigpic.jpg" scale='2x'/> <source src="croppedpic.jpg" scale='1x;640w'/> <source src="croppedbigpic.jpg" scale='2x;640w'/> </img>
Sadly, no. The official way to do Responsive Images is this delightfully baroque construction:
<img src="small.jpg" srcset="large.jpg 1024w, medium.jpg 640w, small.jpg 320w" sizes="(min-width: 36em) 33.3vw, 100vw">
srcset has comma delimited strings, which are then delimited by spaces, with sizes in an entirely different attribute! I don’t know what happens if a filename has a space or comma, URl encoding perhaps?
How would you even begin to explain that to someone just starting out with HTML? Would you be able to quickly and easily construct that tag by hand? Could you debug it if you needed to?
I’m making an example of Responsive Images – not just because I know Bruce Lawson enjoys public flagellation – but because I think they’re a fairly visible symptom of the cult of complexity.
It feels like computer science is in an age of Master Craftsmen who are forming Guilds dedicated to preserving the mystery of their skilled practices.
Just as Master Masons fiercely protected their tools and knowledge – rationing training and apprenticeships – to better enrich themselves, it seems that standards writers, library writers, and technical architects are hell bent on making everything they do as complex as possible in order to preserve their position of power.
"A package manager, install it with npm."
"A package manager, you can install it with brew"
— Stefan Baumgartner (@ddprrt) November 5, 2014
you need to install ruby. now install ruby devkit. now install the jekyll gem. now intall python. (and that's the point where i scream…)
— patrick h. lauke (@patrick_h_lauke) November 4, 2014
python has four package managers (setuptools, easy_install, pip, conda) and all of them are awful. but conda is the absolute worst
— whitequark (@whitequark) October 9, 2015
Part of this is a failure of our attention span. It’s fun to write something new. It’s decidedly not fun to do the grindingly hard work of making existing things better or listening to user complaints and fixing bugs.
We’re also grandiose! “I shall be the one to achieve eternal glory for writing the ultimate…” is a lot more fun to imagine than “I shall toil away unknown as I make this work slightly easier for the next poor sod who has to deal with …”
Here’s what I want you to remember – CPU cycles are cheap, human lives are expensive.
(Now, there are some obvious corollaries – if you’re working on system with extremely limited resources, like a Mars Rover with 1KB of RAM, you can pull off all sorts of intricate tricks to keep performance high. But, I suspect most of us have the luxury of keeping things simple for those who follow us.)
It is our duty to sacrifice our time to make sure everyone else has it easier than we do. Eschew baroque constructions which stoke your ego with their unnecessary complexity and pursue simplicity in all you create.
Selected Baroques From IETF
ASN.1  and BER  are baroque both in terms of the abstract syntax and available on-the-wire representations, and complex to implement.
The Binary Low-Overhead Block Presentation Protocol
However, sending a reset has the undesirable longer-term effect of giving an incentive to future TCP implementations to add more baroque combinations of resending SYN packets in response to a reset, because the TCP sender can’t tell if the reset is for a standard reason, for congestion, or for the prohibited functionality of option X or reserved bit Y in the TCP header.
Inappropriate TCP Resets Considered Harmful
Approaches providing a high degree of flexibility are often baroque; too many options and exceptions often lead to complicated or flawed implementations and serve as a barrier to understanding.
Multicast Security Policy Requirements and Building Blocks
HISTORICAL NOTE: Several of the mechanisms described in this set of documents may seem somewhat strange or even baroque at first reading.
It is important to note that compatibility with existing standards AND robustness across existing practice were two of the highest priorities of the working group that developed this set of documents.
In particular, compatibility was always favored over elegance.
Multipurpose Internet Mail Extensions
This is no DNS issue, in theory all octets can be used in a label, it is a limitation caused by baroque SPF features, and this memo is not the place to specify the handling of labels with embedded dots.
Sender Policy Framework: Email Address Internationalization
While BSON can be used for the representation of JSON-like objects on the wire, its specification is dominated by the requirements of the database application and has become somewhat baroque. The status of how BSON extensions will be implemented remains unclear.
Concise Binary Object Representation (CBOR)