This weekend, I spoke to the audience of the Difficult to Name reading series at Study Hall in Brooklyn. My talk was about the internet, my fears about building and sustaining culture there, and what we might be able to do about it. Watch the talk or read my prepared remarks below. And let me know what you think on
Twitter. I’m @mb there. Thanks to Michael Liberatore for shooting the video and to everyone who helped edit early drafts of the talk.
I want to tell you about a number that scares me: 404. That infamous code you see when that internet thing you meant to visit is gone or it moved and no one bothered to add a redirect or maybe it never existed at all.
I’m curious though: how many of you have ever made something you’re proud of on the Web?
So many of us have written, recorded, photographed, or created important works in our personal and professional worlds that live online. Maybe they’re your bylines at that fancy publication about tiny houses, or your YouTube seltzer reviews, or your graduate thesis about the history of pizza ovens. It’s not really important what they are, just that they exist and they’re online.
Well, until…they don’t. 404: Page Not found. 410: Gone. 500: Internal Server Error. These numbers, or status codes, tell us what went wrong but not really why. This problem, the problem of the disappearing internet, of “link rot”, is no joke. Researchers have found that over 50% of URLs cited in Supreme Court opinions no longer point to the intended content. Roughly 70% of links in academic legal journals are broken, and 20% of all science, technology and medicine articles suffer from link rot. The average life of a webpage hovers right around 100 days.
People often patly state that “the internet never forgets,” that once something is online, it will be forever. In a certain light that’s true. It’s nearly impossible to permanently remove something from the internet, on purpose. But, by the same token, the web also disappears at an alarming rate. 5% of the entire internet is lost every year, and we barely notice.
Making something on the web is not a one-time investment. Someone has to spend money every year on the domain, hosting, and maintenance. But what happens when the financial incentives to do that change? Right now the massive data centers that house all this information use 3% of all the electricity in the United States. What happens when that power gets too expensive? Or when we’ve been online for centuries and we start deleting dead people’s pages? Unlike a film, or a play, or a book, the costs of keeping art and science on the web are never-ending. We’re building one of our most important shared cultural resources on land that we rent rather than own, on borrowed time from a parking meter that’s all but guaranteed to run out.
We have heroic efforts like the Internet Archive to preserve stuff, but that's like burning down houses and then cheering on the fire department when it comes to save what's left inside. It's no way to run a culture. We take better care of scrap paper than we do of the early internet, because at least we look at scrap paper before we throw it away.
He’s right. It is no way to run a culture. We’re experiencing quantitative losses of data on par with the burning of Alexandria every year, and we’re barely blinking an eye as the stuff we’re making vanishes in a puff of smoke.
The truth is: there is no easy fix. But as writers and makers and inhabitants of the internet, we need to demand better of the platforms and services and publications we entrust with our work. It might seem safer to trust the big guys (Facebook, Twitter, Medium) with this content because they have the funding and incentives to maintain it. That’s true today, but large platforms like them have failed before, taking terabytes of data with them. Remember Friendster, TwitPic, Geocities?
There are academic efforts like Perma.cc out of the Harvard Library Innovation Lab that will solve this problem for the most important legal and scholarly works. But we can and must to do better than that.
Starting in 2014, a small group of programmers became obsessed with building what is called “content addressable” version of the internet called IPFS. IPFS stands for “InterPlanetary File System”. And “content addressable” means that files are stored and located by their content instead of an arbitrary and therefore brittle address. As I’m sure some of you have guessed by now, it’s built on top the blockchain. Insert eye roll emoji 🙄. But before you write them off, I think these nerds might be on to something. Their system, which is entirely peer to peer, and inherently resistant to the rot I’m talking about is already being used to build a mirrored version of Wikipedia that will be accessible from countries with oppressive regimes, and was used by those in Catalan seeking independence when the government blocked their pages from being accessible on the web. The IPFS team is building a system by which the websites and apps of tomorrow might be able to defend against this failing foundation, but who knows if it’ll get adopted.
The next time you make something and put it online: think about where it’s going to live, how long it’ll be around, and what you can do to preserve it, even if that means making an extra local backup, or printing it out on a dead tree. The culture we’re building together is increasingly digital, hyperlinked, and accessible from anywhere. But it’s not accessible from any when. We’re losing more and more of it every day. If we’re going to continue making things online, we need to deal with this problem systematically and soon. How? I’m not sure. Maybe IPFS, or something like it that hasn’t been invented yet. Until then, I’ll keep my printer.
I first saw the phrase “Code is poetry” pop up on websites and in conversations about the craft of software development in the early 2000s. Popularized by the Wordpress project, the idea that programming and poetry are similar forms has been the subject of Quora questions, as well as pieces in WIRED, Torque, and Smashing Magazine.
On its face, it is an appealing idea for a few reasons. We programmers would prefer to think of ourselves as lone artists creating clever works of art than a tribe of code monkeys or monastic scribes writing line after line of boilerplate to make a button do something. Sure, some methods might look so concise and beautiful that they remind you of a piece of modern poetry or so archaic that they sound like Old English. And yes, sometimes the variable names and symbols used in a script look sort of like E. E. Cummings if you squint.
But this idea is an example of elitist thinking in our discipline, and it misleads new programmers and the general public into believing that being a software developer requires natural talent, a spark of divine inspiration, or that the code they write should be inscrutable upon first glance. Nothing could be further from the truth.
Great code reads like great prose. It is succinct, expressive, and clear the first time you read it. It tries to be as linear as possible, guiding the reader through tough transitions with the knowledge that one wrong move could lose them entirely. Good code uses language and vocabulary with an understanding of its audience, and it aims for functions with a single main idea, like the paragraphs of a persuasive essay. Instances are narratives—they have a beginning (initialization), a middle (operation), and an end (deallocation).
Well-structured codebases feel more like newspapers or encyclopedias than poetry collections. Individual files operate in a shared universe and are often edited by multiple authors and revised as the facts change. Frequently used objects act like recurring characters: the more you see them, the more you begin to understand how they work.
Even language designers know this. Smalltalk, Swift, and other languages that don’t start with the letter “S” have made English prose the basis of their syntax design. Individual lines of code are called statements, the same word we use in English for the most common type of sentence.
Unlike poetry, computer code does not try to express emotion or evoke meaning through rhythm and rhyme. It aims to tell a story to two audiences: the machines that run it and the people who maintain it. It both narrates and defines how the product it powers works. As Eric Suh points out in Writing code and prose:
Those that I see write the cleanest, most maintainable code are those who write prose well, whether in documentation, in emails, or in their everyday lives.
Many aphorisms about writing style translate fairly well to coding.
So, the next time you write a piece of code and revel in its austere beauty or multi-layered meaning, think about whether it might be better suited as straightforward prose. And while you’re at it, write some actual prose in the form of documentation. Save the poetics for poetry.
A talk I gave last year at the CocoaLove conference in Philadelphia about why you might want to step away from the keyboard and into leadership, and what happens when you do. It’s about the difference between managing programs and managing people.
You’ve been there. You’re sitting in a meeting and your boss, a product manager, or an executive is talking about Q2 goals. They’re laying out a roadmap of the features that are going to be “coming down the pike”. All of a sudden you see it. An innocuous bullet that makes your blood boil: “Auto-invite friends”, “Re-engagement notifications”, or “Disable ATS”.
The particular feature isn’t important. What matters is that you’re the engineer that’s noticed this capital-B Bad Idea. You know why it’s a problem. This time it’s not just the technical debt or the time it’d take to implement. This idea is bad because it trades a worse product for a better “business”: revenue, eyeballs, impressions, you know the drill.
You have a choice in this moment. You can stay quiet and hope it goes away or point it out, question it, and even argue against it. But so often, engineers fold. They ignore their conscience and their gut in the interest of a steady paycheck and an easier work day. Avoid conflict at all costs, especially when that cost could be their job. “Just keep your head down and do what you’re told”, they think, while they twiddle their thumbs as bad product decisions whoosh by. Sure, they complain about it over drinks with coworkers and in one-on-ones, but they don’t say anything when it counts.
We’re better than this. As software engineers and designers, we’re in the room when decisions are shaped, and the only ones who have the power to actually execute them. It’s our responsibility not to forsake the people who trust the apps we make with our silence. To stand up and refuse to implement unethical systems and dark patterns. And even more, to educate stakeholders on the real human costs of their business decisions: the time, attention, money, and trust of their customers.
It’s harder, yes, and riskier. But they can’t build it without us. We get a say. Even if it’s not in that meeting, we can think about the goals they’re trying to accomplish and propose alternatives. We don’t have to hide in our sit-stand nap pods and eye-roll while we engineer a worse world. We can do more than write code. We can research and present better alternatives. We can write memos and make a slide decks to convince them of of our position. We can be activist engineers.
Even though these bad ideas may buttress the metric-of-the-week, they’re at the direct expense of consumer trust and customer satisfaction. They’re a tax on our company’s reputation. We have to push the people making the decisions to measure more than just the number they’re trying to increase. Look at reviews, net promoter score, social media mentions, and team morale. All of these trends matter to the long-term health of the company, and should be treated as such.
This requires long-term thinking and the kind of organization that’s receptive to it. In many companies, quantifiable short term gains are valued more than long-term, qualitative investment. The best companies resist this temptation to make a quick buck and build upon a lasting mission and principles. But even in companies with lofty vision statements, things can go awry. A bad quarter can send the company’s hard-won principles out the window to make room for the growth hackers.
In other disciplines, engineers wear an iron ring to remind them of their commitment to their profession. Though we may not be part of the Order of the Engineer, we can learn a lot from their obligation:
As an engineer, I shall participate in none but honest enterprises. When needed, my skill and knowledge shall be given without reservation for the public good. In the performance of duty, and in fidelity to my profession, I shall give the utmost.
Of course, not every idea you dislike is a bad one, so spend your reputation thoughtfully but forcefully. Make your dissent count, but don’t be a jerk.
Our job as software engineers is to build things that make the world (or a corner of it) better, things that solve problems. But that’s not our only job. It’s also to be gatekeepers: to prevent ideas that we know are harmful from being realized. What’s the worst that could happen: we get a reputation for giving a damn?
You’ve been there. A 10,000 line pull request lands in your email and you don’t even know where to begin. No description provided.
Should you start by installing it, running the test suite, or should you just start scrolling though while your eyes glaze over from the red and green stripes? Is this developer really looking for feedback or are they on a deadline and pressuring you to say “lgtm”. Will your one innocuous comment ignite a flame war?
Code review, or more generally peer review, has a long record of finding defects in not just software engineering, but in science, academia, and many other industries. While some argue about the specific percentages of issues that it finds compared to an automated test suite, or others method of testing, code review is an incredibly useful tool in any software teams arsenal against bugs and poor software architecture. But only if it remains a sharp one. Laziness can creep into code review very easily if you’re not careful.
Jason Brennan has written two great pieces on the topic of diligently writing and reviewing pull requests, and I’ve used his series as an inspiration for my own system. I’ve also found it’s handy to have a short-form checklist to go over when performing code reviews to remind myself what I’m going for. Maybe it’ll help you and your team too.
For the engineer drafting the pull request
Provide a screenshot, GIF, or video of the change if possible. People like pictures.
Explain what changed and why.
List step-by-step how to test the changes.
Link to any relevant task(s) or ticket(s) in the bug tracker.
Link to any existing documentation that could make the change easier to understand for the reviewer.
Mark any areas that are work in progress or require follow up.
Note anything that is waiting on other departments or team members.
Call out any legal, security, or privacy concerns.
If any third-party dependencies have been added, explain what they are and why you chose them.
Double check that the code is styled, documented, and tested to your team’s standards.
Mention people who would be interested in the changeset:
Engineer(s) who wrote the old version
Product manager (if they’re interested)
Give the diff one final pass yourself before asking others to take a look. You might catch a few silly things like typos in comments.
Annotate particularly tricky sections in the diff to make what’s going on even clearer. Maybe even turn these into code comments.
Get a coffee and wait for the constructive criticism to roll in.
For the reviewer
I find it’s helpful to do these in order if you can.
Most importantly, remember that the engineer on the other side of the screen is a person. Try not to be curt or hurtful in your comments.
The Pull Request
Start here to build an understanding of what you’re about to be diving into.
Let your teammate know that you’re reviewing their work however’s customary: a comment, a message, making yourself the assignee.
Read over the pull request description and any linked documents to understand the nature of the changes.
Ask questions about anything you don’t understand or if there isn’t enough detail to properly review.
Does it work as you’d expect? You can write lots of pretty code that doesn’t work.
Alright, it’s time to start looking at the code, line by line.
If code was deleted, was its functionality adequately replaced or is what it provided no longer required?
Does the new code introduced conform to the teams’s standards for style, documentation, and testing?
Does new code make sense when read? Is anything too clever or inexplicable?
Is new code safe?
Does it have the potential to crash or hang?
Are there any obvious race conditions or concurrency concerns?
Is new code fast?
If not, can you suggest optimizations?
Is it well-designed and well-factored?
If not, try to propose alternative solutions or schedule a time to whiteboard with the engineer.
Is it well-named?
Are the names of types and functions obvious and unambiguous?
Do you understand why the modifications were made?
Do the modifications improve the factoring, design, or performance of the software?
Do the modifications change any of the fundamental assumptions that the original code made?
Make sure to understand the implications of new dependencies on third-party code, including their licenses.
Assets and Resources
Do all assets and resources exist in all the right formats and sizes?
Are they finalized and ready to go into production?
Do you understand the effects of these changes and how they can be rolled back?
Adding a system like this to my own pull request reviews has helped me catch a lot more, but I’m sure there are still things I’m missing. If you have ideas about how this checklist can be improved, pull requests are welcome!