Notice, the image contains 2 pieces of mail. The one in back is addressed to me, and I assume I’ll receive it later today. The one in front is addressed to some unknown neighbor in my zip code.

As a security conscious software developer, this kind of “leak” sticks out. And while it’s probably not the biggest deal, I find it interesting that USPS sends me pictures of other people’s mail, and almost certainly sends pictures of my mail to my neighbors every now and again.

This attitude is catching up with us, as our colleagues cheer on vibe-coding AI tools… security, scalability, and architecture be damned!

As for me, I’m happy that the reckoning has come.

It’s time to stop doubling estimates, and derailing timelines over minor changes. It’s time to stop belittling the folks trying to use your software to get something done. It’s time for software to be good, and for software projects to be done well.

The best part of being a developer is that it lets you sink your teeth into problem spaces that have nothing to do with writing code. We build software for everything, so we have to learn about everything. That’s hard, but it’s our job. The best way to to that is to listen. Learn from the sages who know nothing about DB schemas, but everything about dental x-rays, or payment reconciliation, or compliance reporting, or whatever.

It’s time to listen.

Reproductions can be hard

Let’s talk about why.

There are a lot of variables in play when trying to repro an issue. Obviously you can’t simulate the entire universe exactly the way it was when the user encountered the problem, so it takes a bit of artistry to home in on the variables you want to emulate for your repro. In general you can start with a vaguely similar environment, and then match the real environment more tightly until:

A) You achieve the reproduction.

B) Simulating environment conditions in your repro stops giving you useful information about the nature of the bug.

Reproduction strategies

Again, this is more of an art that a science. Your system, your tech stack, and the nature of the bug will all influence how you create a repro. Here are a few flavors that I find useful.

YOLO - Repro on prod (maybe)

As long as the bug isn’t doing harm (compromising data, bringing down the system, creating more cleanup for the team) it may be fine to just try doing what the user did right on production… assuming you have a production account where it’s okay for whatever the repro action is to either succeed or fail. If you are an HRIS software, you probably don’t want to repro a salary change on prod… but if you are a screenshot saas, it’s probably fine?

Mimic the user

Repeat the steps they took to expose the bug. But also, mimic their system variables…

• use the same browser as them

• make your account preferences match theirs

• give yourself the same permissions as them

Non-prod environments

Not all repros should be done on prod. While QA and ops teams all long for pre-prod environments that replicate production, it’s often the case that pre-prod envs are leaner or, at the very least, less trafficked.

In high-throughput systems, this can have a big impact, especially when dealing with recursion, concurrency, batching, or latency sensitive areas of your system.

Mimic prod load.

When mimicking the user’s actions and account state don’t produce a repro, a good next step is to look at load conditions of the system. Load can be tied directly to the user (the have 10x the volume of records than normal users), or it can be ephemeral (the bug happens at peak traffic time in a multi-tenant environment). In these cases, scripting and unit testing can really help. Write a script that inserts a bunch of records or hammers your service with traffic, then run your reproduction and see what happens.

Write a test

I’m not dogmatic when it comes to writing tests, but I find that they really shine for reproductions. Writing a test has the great side effect of expressly documenting the desired behavior. Ideally you can write the test, and see it fail while the bug still exists. This is reproduction! Once you patch the code and the test passes, you (probably) have a real fix.

I love reading history, biographies in particular. When reading a biograpgy I often find myself taken aback at how much self-documenting these historical figures had time to do. Now, I understand that before the internet, and well… much of modernity, there simply wasn’t as much stuff to occupy ones time. And perhaps it’s reasonable to expect that the diary entries of yesteryear will be replaced by the email correspondence, tweets, blog posts, and innumerable digital artifacts that spew from the lives of today’s important figures.

My favorite thing about these historical diaries is that they are remarkably boring. For every momentous entry there seem to be 10 or even 100 “Good weather for plowing today”. Truly mundane stuff, and yet it reveals just how critical a part the rhythm of journaling plays when it comes to drawing any substance out of the habit.

There is a 3rd category of entries that give me hope on my quest to be a habitual journaler. These are the ones that seem like mere humdrum at the time, but end up providing crucial context for important events/timelines/decisions after the fact.

Getting started

For a while I had been feeling like I should start journaling. Then I was gifted a Fisher Space Pen (this is not an affiliate link, I just like the pen!) and a perfect size leather-bound journal at Christmas. And so my journaling career began.

3 months in

Journaling has been a net positive. It helps me clarify thoughts, and convert memories/emotions/thoughts to a sort of “cold storage”, when they might otherwise get evicted from a LRU “hot path” cache.

However — I don’t think I’ve quite reached “peak boring” in my entries. I find myself more likely to journal to make “reactionary” entries… where I write because I’m inspired to by something that happened. Progress for sure, but as I’ve observed in the great diaries of history, a wider net can yield some delightful yet unexpected treasures.

More boring

My goal is to get better at journaling even when nothing spurs me to do so. In fact, I think the mundane days are the ones most likely to benefit from a bit of reflection. It’s easy to think that I know when the important stuff is happening, but I think that strengthening my boring-journal muscle can help recalibrate my relevancy meter to a broader arc of importance… and that seems like wisdom.

The temporary vanquishing of imposter syndrome when you read the bug report, then the source code, and commit a fix with the confidence of the most seasoned sage.

The warmth of logs flickering while traffic spikes on some service you authored, and nothing is burning down or falling over. So you just watch the patterns in the wall of text, as they rise like exhaust from purring engine.

These moments bind us to our craft. They transform us from laborers to artisans. They spur us towards the endless programmer tasks… mastering tools, memorizing shortcuts, and meticulously tweaking setups.

It’s in pursuit of these that I boldly claim that:

Daobeam is the GOAT editor theme.

It’s easy on the eyes, unwavering in its philosophy, and ruthless in its pragmatism.

If you care more about quality software than you do about looking cool, you should give it a shot.

And if you want to really spice things up, try Daobeam’ing your editor even further with this extended vscode config:

{
	"workbench.colorCustomizations": {
		"[Daobeam]": {
			"statusBar.background": "#E0DBC7",
			"statusBar.border": "#171717",
			"statusBar.foreground": "#171717",
			"button.background": "#666666"
		}
	}
}

Daobeam Everything

Once your eyes have feasted on the sepia goodness of a Daobeam themed editor, you’ll want to inject Daobeam into many more of your applications. Here are some configs you can use to do just that:

Warp Terminal

accent:
  left: "#2aa198"
  right: "#268bd2"
background: "#E0DBC7"
details: lighter
foreground: "#171717"
terminal_colors:
  bright:
    black: "#002b36"
    blue: "#839496"
    cyan: "#93a1a1"
    green: "#009100"
    magenta: "#6c71c4"
    red: "#cb4b16"
    white: "#fdf6e3"
    yellow: "#B95C00"
  normal:
    black: "#171717"
    blue: "#268bd2"
    cyan: "#2aa198"
    green: "#005800"
    magenta: "#d33682"
    red: "#dc322f"
    white: "#eee8d5"
    yellow: "#b58900"

Slack

Firefox

Daobeam in the browser? Heck yes! Get the color theme here: link

For a few summers in my teens, I worked on a landscape construction crew run by a family friend. The work was honest, hard, and paid better than most summer jobs that one could find in the tourist town I grew up in. As the youngest crew member (usually by a decade or 2), I knew hardly any of the “tricks of the trade” that the professional crew regularly employed to get work done quicker and with less labor.

This knowledge gap impacted how productive I could be at work. If left to my own to complete a new (to me) task, it might take me 3 hours finish what a seasoned vet would have knocked out in 30 minutes. A 6x “rookie tax” might sound extreme, but really I think this is pretty conservative, especially when we superimpose this idea onto software engineering.

I found myself most productive when some “heavy hitter” from the crew would take a few minutes to do “setup work”, to get me up and running. If tasked with planting a row of 4 shrubs for example, perhaps the landscape architect could mark where each shrub should go, then maybe the excavator operator swings by and digs crude starter holes with his machine.

These are small, but high leverage tasks for the experienced folk. They unblock me on multiple fronts that are beyond my current skillset. Instead of fretting over placement, or digging holes by hand, I’m now focused on the things that I’m proficient at while pushing the task forward.

Hand finishing the holes to proper depth, cutting the burlap off the root balls, fertilizing, planting, cleaning up the top soil, laying down a bit of mulch. All right up my alley, and critical to getting the job done.

We should think of building software like this. Throwing a junior engineer at a new problem with no context is doomed to, in the best case, take longer and be more painful than it needed to. The job of a senior engineer is to find the setup work that frames the tasks of others properly. Stubbing out 3 pseudo functions in the right parts of the code, writing a script to run something locally, coming up with a mock json response for a new API endpoint.

This stuff is easy and doesn’t require much time investment, but it serves as a critical guide wire for someone less familiar with the task. And best of all, it’s not infantilizing. You’re offering a fuzzy glimpse at what the solution looks like, and most importantly, you’re letting them know the kind of things they need to learn to level up themselves. And if they are any good, they will.

Sometimes cleanliness comes at a cost, and that cost is the very strength of the thing we are trying to build!

A Lesson Learned

I recently launched a feature that I thought was super clean. Users would navigate to a page, the page would fire up a websocket connection in the background, and display incoming data the moment our system received it! Awesome.

Then I sat down with some actual users…

They liked the basic idea of the feature, but their foremost suggestion caught me a little off guard.

“Can you add a refresh button?”, they asked.

“Huh? What do you mean, the data is always live, there is no need to refresh.”, I explained.

They walked me through their workflow. How they would navigate to the page, wait for new data to come in, and get anxious when nothing showed up for a few moments.

Then it hit me… there was nothing “wrong”, the page accurately and reliably reflected the latest data, BUT it didn’t tell the user what it was doing, or why nothing had changed, or what it was “looking” for new data in the background.

I made it too simple, and because of that users were left confused, hitting the refresh button in their browser, eagerly awaiting for the data on their screen to update.

The Fix

Thankfully the fix for this one was pretty straight forward. What was needed was presenting some additional state indicators to the user. A pulsing “live connection” indicator… a timestamp from the last “keep alive” message we transmitted over the websocket.

Really, just a few subtle hints that the page was working, that the tool was looking for new data for them, and that they didn’t have to finagle with it to get the latest result.

Conclusion

Clean isn’t everything. Step back and make sure that your design gives the user something to hook onto so that they understand what’s happening, even in passive states.

Naming things is hard because it is important. Our packages / classes / functions / methods / variables / etc become the API of our shared tool belt. Good names keep our work shop orderly, and help us catalog which resources we have at our disposal.

My favorite engineers to work with are the ones that strike a mythical balance of context, conventions, style, and humor in their naming of things. They understand that authoring code gives them the very special power of controlling what flows from their colleagues fingertips (sort of like the kids book my son enjoys, where the characters figure out that they can get the “reader” to say whatever they want).

This is an intimate power. The “language” of our codebase changes how we reason about the code we write. The same way that the language we use in society shapes our collective thinking about issues.

That said, here is a list of attributes that I think are common to well named things.

• They are “SEO” friendly

• They lean into convention

• They prefer terseness without sacrificing meaning

• They are considerate of collisions

• They are guessable

• They make you smile from time to time

I’ll expound on these below.

“SEO” Friendly

Big code bases, with lots of contributors get searched. Most engineers, especially in established projects, will default to using what’s there already. Common tasks like authentication, authorization, error handling, logging, etc should have very obvious and highly searchable names. For example, “auth.DecodeJWT(…)” would be a solid name for a function in the “auth” package that handles the decoding of JWTs. Whereas “helpers.Validate(jwt)” misses the mark.

Leaning Into Convention

Good convention is really powerful and might be the highest leverage tactic for naming things. I’ve worked in a big mono-repo that adopted a fun convention of adding an “-y” suffix to core utility libraries. Think “stringy” for string helper functions, “timey” for date/time stuff, or “randy” for… you guessed it, randomness utils.

This had a few benefits:

• It made naming new packages a non-thought

• It increased readability, as util funcs were name-spaced with the obvious convention

• Utility code discovery was easy, just look for the appropriate “-y” lib

• Gaps in utilities were obvious (no “-y” for the category you wanted? time to add one!)

Terse, but Meaningful

Long names are well intentioned, but often un-helpful. For example, if you are making a SaaS app for veterinary clinics, you probably don’t want a bunch of functions like:

• “CreateNewVeterinarian”

• “DeleteVeterinarian”

• “UpdateVeterinarianContactDetails”

These convey plenty of meaning, but there is a lot of extra over-head when it comes to typing and line length that we can 86. The better way would be:

• “CreateVet”

• “DeleteVet”

• “UpdateVetContact”

That’s easier on the eyes, the fingers, and the line wrap :)

Considerate of Collisions

Names should lend themselves to being considerate of their caller’s context. For example, maybe you have a database library that exposes a “reset” function. If the reset function is always chained to the package name, or a method on some other class/structure, than I’ve got no beef. But, if it’s a stand alone function call, like in this pseudo javascript code…

Inconsiderate Version 😿

import { reset } from '../lib/db'

const cool = () => {
  reset()
}

This is inconsiderate. The “reset” call on it’s own gives no hint that it’s related to the db, and once our “cool” function does some more work, this code will be harder to read and eventually might even run into a collision scenario where there is some more locally scoped “reset” logic that we want to run. Yikes!

Considerate Version 😎

import { resetStore } from '../lib/db'

const cool = () => {
  resetStore()
}

This is a considerate function name. No matter how verbose the “cool” function gets, we know that “resetStore” is resetting a data store, not something else.

Guessable

The best names are guessable. Convention helps a lot here, but also, so does logical code division and function implementation.

Let’s consider a “User” class with a handful of methods that send various emails to the user. You want your code to look something like:

// this is cool ✅
user.SendPasswordResetEmail()
user.SendVerificationEmail()
user.SendNewDeviceEmail()

vs

// not so much ❌
user.SendPasswordResetEmail()
user.Verify()
user.NotifyForNewDevice()

The problem here is not the method names themselves, but the fact that they are wildly inconsistent.

Smile!

Remember, our code gets compiled and interpreted by computers, but it gets read by other programmers. With that in mind, you should inject some sunshine into your naming when appropriate.

I once wrote a method for presenting a “Toast” in a web UI called “xplode”. Calling

const toast = new Toast()
toast.xplode()

Would render the toast in it’s “something went very wrong and we have no better options” state.

This name doesn’t exactly follow the guard rails I’ve laid out… it’s not very SEO friendly, doesn’t follow any hard conventions, and yet… it somehow fits the bill, and stuck in the minds of the team. It had some soul, and described what it did poignantly.

There are a lot of conveniences for conventions like this. Normalization for managing access to systems, “guessability” for new comms, avoiding collisions, and fewer squabbles over who gets “john@{companyDomain}”.

But, IMO, this is a missed opportunity for most companies.

Why? Because a work email is one of the very first, most long-lasting, and most frequently observed signals that an employer gives to an employee.

Think about it. Work email is square one of employee onboarding. It then gets embedded into their daily workflow… as the use it to log into systems, or share it with others to communicate.

The difference between a “cool” email and a conventional email can be a big deal. One tells the employee that they are a record in an identity database, a cog in the machine. The other tells the employee that they are an individual with unique attributes to bring to the company.

While I’m not an advocate of the “bring your whole self to work” idea, I do think that embracing someone for their unique skillset and perspective (when it comes to work things) is much better than the templatization signal in the conventional email schema.

This is a no brainer for early companies, when there are fewer collisions to worry about. But even after you hire a few “Bill”s or “Janet”s, you can still offer your team a better email than first.last. Here are some ideas:

Some Better Convetions

First Name Only

{firstName}@{companyDomain}

Example: shayne@example.com

Last Name Only

{lastName}@{companyDomain}

Example: osullivan@example.com

First Name + Last Initial

{firstName}{lastInitial}@{companyDomain}

Example: shayneo@example.com

Initials

{firstInitial}{middleInitial}{lastInitial}@{companyDomain}

Example: sko@example.com

Professional Handle

You probably don’t want emails like “sc00terDude15@example.com”, but most adults have a deep bag of “handles” that they are used to creating on various sites. Be open to one of those when there is a collision.

For me, that may be something like:

• shayneosull@example.com

• osully@example.com

• sos@example.com

• shayneos@example.com

Be Flexible

Maybe the most important thing is just to recognize that the work email you give someone is indeed a signal. If you are an early company and can’t give them “firstName@”, let them propose a reasonable alternative, or let them pick from a few ideas.

It’s a small thing, but it sends the right message.