Stains

Yuzu
4 min readMay 12, 2021
Image from Pixabay

A few days ago, my company transitioned a fairly large number of employees onto the project I’m working on. Our once peaceful project Slack channel was bombarded with the woes of many employees getting error messages that they (nor I) understood. Fortunately, I had a free hour or two to spend due to wrapping up my tasks early in a sprint for once. What I found was what I’d like to call a stain.

A stain is a particular type of tech debt. As a form of tech debt, they make working in the project harder and definitely need to be addressed at some point. There are two things that make a tech debt a stain in particular:

  1. The problem does not harm anyone who is actively involved with project. In many cases, you may not even be aware that it is a problem until someone new to the project comes along.
  2. The solution to the problem involves much more work than the workaround.

Imagine a carpet in your home. One day, while enjoying a glass of wine, you unwittingly spill a few drops onto it. None the wiser to your mistake, you carry on with your life and never notice it. The stain from your wine dries. Removing it is no longer a simple matter of dabbing with a cloth and warm water. We’re talking full “treat the carpet multiple times over the course of a day with specialized cleaner” territory. A few months down the line, as you clean your home in preparation of guests, you discover the stain. Small enough to have been easily missed for months. Big enough that it’s a problem. You don’t have the cleaner, and you really have better things to be doing right now.

We decided to use Unity’s package management system as the “proper” way of distributing our library code. As part of that “properness”, we decided to put our package server behind auth, so that no pesky hackers probing our services could just make off with our entire library of support code. So far, reasonable, good software development.

Then came the stain. You see, in order to get Unity talking to a package server with authentication requirements, it needs a token. To get that token, you install Node, so you can use npm at the command line to add a user to the package repository, authenticate as that user, then grab a token from a hidden file in your home directory that is generated when you do so, and put that into a file with an esoteric file format with a particular syntax and at a specific location on your machine which changes based on what operating system you’re using.

In this case, the debt was relying on this process. Several of us read this documentation, actively followed the steps within it and decided that making everyone in our project depend on this series of incredibly unintuitive, specific process was okay. None of this is excessively hard or complicated. It is well documented. For most engineers, it is a trivial amount of work. And there are enough ways for things to go wrong that it should be a machine-managed process, not a human one.

Stains are the result of bad engineering at the user level. Nothing in this chain of requirements is bad policy. It’s the means by which that policy is achieved that are unreasonable.

On our end, the process is clearly error prone, manual, and easy for a computer to do and do correctly. A simple shell script could perform the tasks listed in the documentation. We shouldn’t have let this solution go live, and we should have spent the time to make sure all of our systems and users were ready.

On Unity’s end, they made this process in the first place. Why does a user need to go an install an entirely separate software package in order to authenticate with a Unity product? Unity has a means of establishing user identity: a Unity account. Why not make that the mechanism of authentication, like it already is for the Asset Store? Certainly, doing this would have taken more time and effort than reusing npm’s authentication systems. They’re also more sturdy, permanent solutions that don’t require your userbase of millions to set up and maintain yet another thing in order to use your product in the way you want it to be used.

The worst part is that the simple fix is easy and long-lasting. An engineer could easily take the 5 minutes worth of time it would take to go follow those 5 steps on every computer, and it would be solved today. The alternatives are:

  • educate every employee on this (error prone and unreasonable to expect non-technical users to be able to troubleshoot complex, technical systems)
  • to build some form of system, ideally one that requires minimal interaction from anyone, engineers included, to authenticate on our behalf (days to possibly weeks worth of time, have to maintain it in the long term, still need to educate employees on it)

Implementing the alternatives aren’t really advantageous for us as users over just following the bad process.

The solutions to stains is good software engineering. It’s not having a bad process in the first place. It’s thinking about your end-user as you build your software and putting in the work to make their life better. It’s not easy, and it’s certainly more time consuming. But it is necessary in a world where software is so interdependent and complex. What seems like a way to save a few days or weeks worth of effort can end up generating months or years worth of trouble for your userbase. Let’s do better, for our own sakes.

--

--

Yuzu

Professional games programmer, aspiring game designer, musician, DJ