SemiSafeForWork

Heirloom quality software

Thu, 18 Dec 2025 20:42:00 +0000

Using LLMs or AI to develop software isn’t new-new, but it’s still new-ish and nascent. Over the past year, my usage has gone from “this chatbot is a stupid party trick” to “this auto-complete is getting better” to “hey $LLM_OF_THE_WEEK, write me a whole app that does… something”..

I’m constantly vacillating between “the game is forever changed” and “what a pile of junk, if this is the future, humanity is cooked”. We are all still learning what works, what doesn’t. What is vaporware nonsense, and what vaporware nonsense just started to work this morning.

About six months ago, I was responding to an email about vibe coding (in case the term dies soon, that’s coding using only prompts) and an analogy struck me and stuck with me.

vibe coded software is great for what it is: getting an idea into reality. It’s akin to fast fashion clothing, where traditional software is closer to a bespoke tailored suit.

I like this analogy because fast fashion isn’t inherently bad¹. If fashion changes drastically between seasons, why spend resources on making something durable that will never be worn again? We can now do the same with software. It’s become cheaper to greenfield a whole product with a fresh and improved series of prompts.

The other end of the spectrum is that system that is intended to be durable, generational, repairable. The heirloom quality tool. This is for software that needs that extra care, and craft. I think this is where in-depth engineering will continue to thrive. Reinforce the critical cores with the added strength of human ingenuity and pattern recognition.

Where I think we, as an industry, need to do better: recognizing where each approach is important, where it fits the task. You could make a peanut butter and jelly sandwich with a screwdriver, but it’s never going to be the right tool for the job. I don’t care if it’s a Phillips, flathead, or a hex driver.

I asked an LLM to review this post for grammar, it replied with “The PB&J/screwdriver metaphor doesn’t quite work—screwdrivers spread just fine, which undercuts your point about wrong tools.” proving the robots don’t understand peanut butter.

As of this writing, my experience with AI driven code is that it gravitates away from reusable code. This should be expected. Reuse requires context, and context is expensive. This already creates a natural tension for code that has a large impact on the user base.

Since the LLMs run in a limited lifespan sandbox, the constant reset between sessions makes it impossible to genuinely understand the scope of any change they introduce outside of the local environment. Their universe is defined by the narrative of the immediate prompt. I feel this runs deeper than chaining session contexts together. As engineers, our job is evolving into acting as higher order context filters, with visibility of scope, and consequences, outside ourselves.

One interesting thought as we start to think of the whole artifact as being disposable: we care less about the insides. There are already whole suites of scripts I’ve generated where I’ve never checked the contents once I accomplished the actual task. Build, apply, delete.

A friend of mine pointed out this is reminiscent of neural networks in general, a confusing black box whose inner workings we barely understand. If that is true, am I now simply the product manager? Does that make the LLM (and its subagents) the engineering staff building the system? If that is the case, we have functionally shipped the org chart.

And with that, Conway’s law has struck again.

Except for the environmental impacts. Those are bad. ↩

Jason ain't about the jazz, man!

Fri, 14 Oct 2022 13:03:00 +0000

Javascript and the interchange format it begat, JSON, have subtle complexities that aren’t necessarily obvious. They are both very quick to learn, and powerful, which makes them seem deceptively simple.

Before jumping in, let’s start with the basic understanding that JavaScript has always been a weakly typed language. This is what makes it so forgiving. That isn’t to say it’s untyped, there actually are some basic types:

string
number
list
map
null

Those are the only real types that can be represented by JSON at the extremes, but the Object Notation part of JSON indicates that more complex classes can be described.

Let’s say we have a system that determines the number of pods deployed in each data center, currently in the us-sfo data center we have 180 pods, and 47 pods in the us-sjc data center. We could write a JSON data structure that looks like this:

{
  "data_centers": {
    "us-sfo": 180,
    "us-sjc": 47
  }
}

This makes sense, right? It’s built for expansion in case we want something other than data centers, and all of the counts are there.

Let’s look at it when we convert it to a strongly typed language, like kotlin:

data class DataCenters(
  @Json(name="us-sfo") sfo: Int,
  @Json(name="us-sjc") sjc: Int
)
data class Response(data_centers: DataCenters)

A few things pop out here. The names are already causing trouble due to language mismatches, but that’s really a signal of a deeper mistake that is happening. This data structure mapping is papering over the fact the underlying data is really structured to be:

data class Response(data_centers: Map<String, Int>)

The underlying data is important, because as new entries are added, the code will push itself in the direction towards the Map. If we were to add one us-xyz data center, it’s trivial to add one more member variable to DataCenters but if we add 5 more, developers are going to stop adding distinct members and start to just leave it as the less descriptive Maps.

Eventually time will pass

With this, it hopefully becomes apparent that while it’s quick to write, it’s also quick to forget what the integer represented. Was it the total capacity of the data center? Was it the data center’s internal serial number? The elevation? Oh right, active pods.

What we have run into here is the fact that a Map (or Dictionary) can be substituted for lists of unique items, but the pain isn’t felt until much later. When storing in a Map, we automatically do a premature optimization of removing the duplicated name from the object since it also appears in the key field.

What we are really trying to describe is a collection of data centers. Data centers already have two attributes we care about, which fundamentally makes them an explicit object themselves.

data class DataCenter(name: String, deployedPodCount: Int)
data class Response(data_centers: List<DataCenter>)

This leads to restructuring the original JSON as

{
  "data_centers": [
    { "name": "us-sfo", "deployed_pod_count": 180},
    { "name": "us-sjc", "deployed_pod_count": 47 }
  ]
}

This also has the benefit of being more descriptive for new users and consumers of the data format.

Why does this matter?

When we default to the use of Map as a collection, we are forcing an access pattern. Random access by key. All code that doesn’t conform to that access pattern becomes substantially harder to read. If we wanted to just find the most populated datacenter, we would need:

if (dataCenters.sfo > dataCenters.sjc) {
  if dataCenters.sfo > dataCenters.xyz {
     ...
  }
} else if (dataCenters.sjc > dataCenters.xyz) { ... }

// or if we had stopped adding attributes and left as a Map

dataCenters.keys.reduce { dcLeft, dcRight ->
  if (dataCenters.getOrDefault(dcLeft, 0) <
        dataCenters.getOrDefault(dcRight, 0)) {
    dcLeft
  } else {
    dcRight
  }
}

compare that to

dataCenters
  .sortedByDescending { it.deployedPodCount }
  .first()

// which the IDE will encourage you to simplify as:
dataCenters.maxByOrNull { it.deployedPodCount }!!

The latter is far easier to read and comprehend, and doesn’t require people to remember context of what each integer actually is. This is a trivial example, so even the hard mode is trivial. Maps of maps of maps of ints become a cognitive nightmare.

The Big Os are lying to you

An astute reader who has just finished a gauntlet of FAANG interviews will probably respond with:

But a Hashtable has a lookup time of O(1) as opposed to this O(n) nonsense you get from sorting that list. You fool! You’ve wasted precious cycles!!

In the case of the non-key lookups, we are going to have to iterate the entire key set THEN do the O(1) lookup which isn’t free. For the best case lookup by data center name, it’s also important to note that algorithmic complexity doesn’t account for the fact that hashing a string is constant time, but for low values of n (which is most cases) the CPU effort to scan an entire list with string comparisons will be negligible.

The amount of coworker time you’ve saved by making the logic readable will be orders of magnitude higher, and you will have made the world a slightly better place.

.last()

It’s JSON (JS Object Notation) not JSMN (JS Map Notation), so if you have a Map, it better be for an object of some kind. If the name of the entry is a plural, you probably meant to have a list. This applies to data exchange, configurations, and even YAML.

Testing in 3D

Wed, 26 Aug 2020 13:23:00 +0000

Automated testing is a facet of software engineering that most people agree holds value, but usually the engineer will wander off before offering any further clarification. There is somewhat of a blind faith that given full coverage, an engineer’s work is complete and they can continue solving the rest of the business’ problems.

The issue with carelessly creating tests without purpose is that changes and enhancements to a large system can become unnecessarily more complex and difficult over time. It is worth noting here I will not differentiate between unit and integration tests, as in practice the lines get very blurred depending on the practitioner. Instead, I will take a look at three conceptual purposes of automated tests in an effort to define what makes them useful.

Design

This is the category of tests most frequently created when practicing Test Driven Development. If you are not familiar with this, you can think of it as micro-specifications. You define what you are going to build by way of a failing test, it fails because you haven’t built it, and then you make what you said you were going to make. The test passes and you repeat.

Design tests are helpful for making interactive notes and / or plans for your code in the event you get distracted. They are also extremely appropriate when prototyping, research spiking, and concept-proving. Instead of pushing data all the way through a system to identify if your change had the desired effect, you can measure it in some degree of isolation. Design tests also reduce the likelihood of you creating a proof of concept then dropping it on a more junior engineer to clean up after you.

Not all codebases are appropriately set up for this. If there is very tight coupling in inappropriate places, it can be harder to generate more surgical design tests. With some time, care, and effort a codebase can be reshuffled to make smaller validation points more natural. Those kinds of changes should always be considered valuable refactoring efforts.

Document

Good code documents itself. This is an evergreen lie that software engineers love to tell each other. It does not. Code is sometimes legible to the original author. Sometimes even up to a week or two later. While the commit message and the associated tickets can provide more supplementary context, consider using tests to also cleanly illustrate the purpose of a set of methods.

Documentation tests differ from Design tests as the intended reader should be at a broader scope. It is very important that Documentation tests do not traverse a maze of inherited setup. There is a fallacy amongst some developers that DRY applies to tests. When abstracting away setup, you force the reader of a test to track down all aspects that may be affecting the current operation. Imagine having to read this entire post to understand a single sentence. Then starting over the entire post to understand this next sentence. As entertaining as I am, that is still pretty brutal.

Instead, abstract away only the parts that are irrelevant. If they are irrelevant, can something like dependency injection abstract it away further? This can lead to code that leans into testability. Embrace testability. There is a benefit both from the validation, and the predictable structure for readers.

Defend

If you are like me, your code always runs flawlessly the first time. The second time it runs, it is even better. After you increase the load 10x, the CPU is reprogramming its own microcode in awe. But, as a thought experiment, let’s pretend we make mistakes. Imagine that we get woken up at 3am due to a production error which has led to nefarious computer hackers, undoubtedly wearing hoodies, breaching the system. Since very clearly i should only be below 200, we notice problem, fix it, and then go back to blissful sleep.

Or we could write a very specific test. A test where when i is allowed to equal 200 and terrible bad things happen. This test must reference a ticket or incident number in a very clear way, by name or comment or whatever your team agrees on. What we are trying to do here is to signal to all readers:

This is real life, real life is messy. If you changed something and this test failed, you were about to make an unexpected mistake. That mistake may ruin a dream where you are, in fact, a puppy.

As more participants enter a codebase, they all want to put their touches into it. By establishing a set of defensive tests, you create an environment where that is a safe endeavor. Just have an agreed upon prefix or standard that communicates to later readers these defensive tests were born out of production events. Treat these tests with more care and respect than other tests. Someone may have literally lost sleep over them.

Bonus Dimension: Deleted

Why limit ourselves to a boring, predictable three dimensions? The most exciting type of test is the one that can be deleted. I’m not advocating taking a clean slate approach and wiping everything out, but I am suggesting that tests are not necessarily permanent.

Design tests are the most prime candidates for deletion. By their nature, design tests are fragile. They tend to be generated in a stream of consciousness for the benefit (only) of the original author. If the true purpose has been accounted for by another test, send the design tests on their way. They should be considered as scaffolding; it serves a purpose during construction, but makes life less pleasant after everything is built.

Documentation tests, and subsequently defensive tests, tend to linger. These should be clear to the reader when they no longer belong in the system. If a test refers to a feature that has been deprecated, it is a good time to remove it. Sometimes, these types of tests can aid removing dead code as it will document a subsystem that is now vestigial.

Mind the machinery

A distant cousin of design tests are machinery tests. These are the types of tests used to prototype and inspect a 3rd party dependency, library, or service. While good for learning, these have absolutely no place in your project. The truth is that if your SQL query worked once, it will continue to be valid SQL for every commit moving forward. Unless you live in the make-your-own-rules anarcho-paradise that is untyped JavaScript, you should be able to trust that your dependencies are stable enough to not break your builds. No value is generated by validating these types of things, but countless person-hours are lost trying to diagnose them.

Good tests tell their own story

You can’t judge a book by it’s cover. But you can, and you will. The name of a test will be your first, and sometimes only, impression of what is going on. Ensure your tests have descriptive and accurate titles. Convince later readers that you had at least a semblance of an idea of what you were trying to do.

In the same vein, your test should tell a story. It may not be an exciting one, but it should have a cohesive plot. Set the stage for what is about to happen. Then, the big reveal, everything worked! Clean up the loose ends and continue on with the sequel. If there is too much going on in one test, try to refactor or abstract away the parts that do not add to the narrative. When this is pervasive, the code can naturally restructure into a more readable state.

Code Review for Great Goodness

Thu, 06 Aug 2020 16:48:00 +0000

Code review is a common practice for professional software teams. As an author, there are several things you could hope to gain from having your code reviewed:

Other people’s opinions on stylistic and naming changes
A rigorous defense against logical and syntactical flaws
A chance to communicate better and share knowledge with your peers
The respect and adulation of the aforementioned peers

In reality, nobody genuinely wants the first one. Automated testing is far more effective for the second. I will only focus on the latter two gains. The real ones.

Keep the change succinct

Keep your pull requests both small and focused. If you move stylistic and refactoring changes into separate changesets, it will allow reviewers to focus their mental energy on understanding and internalizing the important logical changes in isolation. I am a fan of conventional commits, which lends itself to this naturally. Calculated and focused commits also reduce the chance of you creating a wall of code that nobody ever finishes reading.

A small PR is a reviewed PR.

If you find the description you are writing contains several related but not tightly coupled changes, consider turning the pull request into a draft, and isolate the changes into their own reviews. This reduces the cognitive burden of the reader, allowing them to focus better. It also gives you a chance to give your code a quick pass first.

Add context

You spent all this time being great, make sure everyone else understands just how great you are. A poorly capitalized sentence fragment as a title for a pull request shows your reviewers how little you value their time.

Whereas, a detailed description, with links or references to the associated ticket gently indicates that maybe this is worth more of their time and scrutiny. The time the reviewer saved trying to understand what it was they were supposed to be reading can now be spent returning value back to you.

feat: Add support for the legendary MultiFrobulator

As part of the effort to increase maximal Frobulation, this
adds support for the experimental, yet promising
MultiFrobulator. There is a subtle concurrency
gotcha that should be mitigated with the extra Glurm.

Do not operate after a large meal.

ticket: FRB-2021

Let your first reviewer be you

You can still have code review on a team of one. Once you have pushed your code and kicked off your automated tests, take a walk, nap, or ride a bicycle to a karaoke party. Once you give your brain a chance to recharge, try reading your own PR. Be liberal with minor suggestions. Anything that was not immediately obvious to you will likely be far more confusing to other readers, or you again six months later.

This also makes a good time for documenting your thought process. You know, the transient comments that matter the most in the first 24 hours of a change and are absolutely worthless 197 commits later. By preemptively commenting on sections, you can encourage dialog with your other reviewers. It also highlights important areas they may not have known required more scrutiny.

Stop with the rebasing already

Once you finish your initial personal review, make a promise to the universe that you will not rebase for the lifespan of the pull request. While rebasing (and amending commits) can result in a clean, expert looking commit, it robs your readers of the learning opportunity to see your thought process. It also has two very negative effects on your reviewers.

Assume your reviewer will be pulling your code locally and conducting at least a partial review in their IDE. Both IDEA and VSCode have dedicated pull request review functionality. With most modern languages, to genuinely understand what is going on with type inference, polymorphism, implicits, and even just library calls, the IDE is a necessary tool even for reading. When you rebase or amend, you are generally also force pushing and making it incompatible with the branch your reviewer was already interacting with. This causes your reviewer more effort for your own vanity. This will result in a ~~disinterested~~ disengaged reviewer.

The second negative is that any feedback already solicited gets washed away. Either the comments do not line up correctly, or the changes you did implement become hidden. If you only updated 3 out of 4 similar suggestions, you are forcing your reviewer to start over from the beginning. This will result in a discouraged reviewer.

Never rebase once that first reviewer comments until you are ready to merge. Squashed merges accomplish the same streamlined final commits without introducing the problems generated by rebasing.

All that glitters is not code

One aspect of code reviews that seasoned developers rarely enjoy is unwanted style suggestions. Unfortunately, when people have less experience reviewing code, the stylistic and pedantic commentary is simplest way to start. We emulate what we have seen, and your very first reviewer was probably a compiler, or a linter.

A healthy team will have a general guideline and working agreement for what is considered appropriate suggestions for reviews. In addition, it is helpful to have a common shorthand to convey the difference between required changes and light suggestions. Conventional comments exist for this purpose, similar to the conventional commit messages.

Even with guidelines, gold plating suggestions are inevitable. While it can be frustrating, try to assume it is not coming from an antagonistic, or inexperienced place. Consider, perhaps, that the pull request could have started with a more detailed description, better definition, or more breadcrumb commentary to guide the reviewer. Even if they do not realize it, the gold plater may just not have enough context of the problem or understanding to ask deeper and insightful questions. It’s not that they don’t care, but you may not have given them a reason to.

In Review

If you take a small bit of extra time before throwing your code out for review, you can solicit much more valuable feedback. This serves far more value than reviews solely for the purpose of checking a box.

Running WireMock with Gitlab CI Services

Sun, 10 May 2020 19:56:00 +0000

In a healthy project there will be a lot of tests. One of the tools that makes for convenient testing is WireMock. If you are not already familiar, WireMock is a service that listens for HTTP requests matching certain conditions and replies with canned responses.

Change control for requests

One of the features I like about WireMock is that the canned responses can be defined in individual JSON files, loaded at startup. This is convenient for tracking the mocks via source control, as well as making them portable between projects of differing source languages.

Here is a sample that defines the request for a fictional status endpoint. The response can also be defined inline, but if it is non-trivial, or binary, I prefer to store that in an additional file, which is very easy to do.

{
  "request": {
    "method": "GET",
    "urlPath": "/api/status",
    "queryParameters" : {
      "withDetails": {
        "format": "json"
      }
    }
  },
  "response": {
    "bodyFileName" : "sample_status_response.json"
  }
}

Using WireMock in practice

For local development, it’s very easy to set up run a WireMock docker image. Frequently, images will expect the stub mapping files to be mounted in the image. With docker-compose this is a trivially easy process. (The semisafe image passes all docker image arguments directly to the WireMock binary)

mock-api-x:
  image: "semisafe/wiremock:latest"
  command: "--root-dir /mocks"
  volumes:
    - ./mocks/api_x:/mocks
  ports:
    - "8081:8080"

At this point there is now a local server listening for incoming connections. Any unit tests that connect to localhost:8081 with a request matching the defined stub will get the defined response in return.

Integrating into the build pipeline

An important part of any build pipeline is to ensure tests are run during the review cycle. In GitLab, having build pipelines with test coverage indicators is included in even the most basic plans. To provide support for ancillary dependent systems, GitLab CI provides services. The documentation for this feature is a little sparse. It looks similar to docker-compose because it’s yaml based, and relates to docker images. In reality, the feature set is not similar at all.

Mounting volumes into service containers is not reliably supported with services in the Gitlab Runner. After trying to hunt down a solution to mount the mapping files from the repository under test, it finally occurred to me that I was taking the wrong approach. I have already been using Flyway for dynamic schema application for quite some time. WireMock also has an Admin API that allows for stubbed requests to be added dynamically.

This led me to throw together a small tool to automate the process of taking the mapping files from a local filesystem and posting them to the Admin API.

This can be run manually with the following:

yarn start -m /path/to/mocks -h mock-api-x -p 8081

Complete the build image

Alternatively, wiremock-loader can be embedded in the base Docker image used for the CI build process (here is the one I use for Scala / Play projects that also includes Flyway). Once it has been added to the base build image, each service can be initialized before running the tests:

build:
  stage: build
  services:
    - name: "semisafe/wiremock:latest"
      alias: fake-api-x
  script:
    # If you have a DB, now would be a good
    # time to call Flyway migrations

    # Load the WireMock service
    - wiremock-loader -m ./mocks/api_x -h fake-api-x -p 8080

    # Execute the actual build / test-runner
    - sbt clean coverage test coverageReport

This can now be used to create a separate WireMock instance for each required dependency. While it could be easier to combine all dependencies into the same WireMock instance, that could hide subtle issues where hostnames get mangled or confused in the configuration.

React & Typescript & Storybook

Sun, 03 Nov 2019 23:58:00 +0000

About once a year or so I create a fresh React project and realize that over the course of the year, everything has changed.

For the benefit of future me, and current day you, I have recorded the most recent process after trying several times to determine the most clear and concise method.

The following tooling is my current preference and target:

React
TypeScript
ESLint
AirBnB lint rules
VSCode as Editor of choice
Jest for testing

Typescript enabled React

For creating a basic React application, the easiest way to get started is with Create-React-App. For adding typed support to JavaScript, the options are generally either Flow or TypeScript. I personally prefer TypeScript, but honestly do not remember why I made the switch from Flow.

Support for generating a TypeScript application is now baked directly into Create-React-App. (source)

yarn create react-app new_app_name --typescript

Storybook

Storybook is a tool that allows presentation layer components to be viewed and interacted with in isolation. This provides developers the ability to rapidly iterate on portions of an application that would normally be difficult to access or require fragile scaffolding to examine.

In the same way that heavily unit tested code tends to shape the structure of testable code, Storybook tends to encourage cleaner boundaries on the visual versus programmatic layers of React applications. This allows the more presentational components the same level of scrutiny and verification unit testing gives to logical layers.

For a period of time, getting storybook into a create react app had some manual steps. At this point, the simplest (and least error prone) method is to just use the CLI tooling provided by the Storybook developers. (source)

npx -p @storybook/cli sb init

With the currect Storybook installation, the only primary difference is that stories are still expected to be in JS files. This can be augmented with a simple update to the .storybook/config.js file (specifically \.stories\.(js|tsx) in the third parameter of require.context()):

import { configure } from '@storybook/react';

// automatically import all files ending in *.stories.js
configure(
  require.context(
    '../src/stories', true, /\.stories\.(js|tsx)$/
  ),
  module
);

ESLint for Linting

This is important. Depending on whatever other blogs you have read or skimmed, stop using TSLint. ESLint is enabled, works correctly for TypeScript and is now the preferred method.

The bulk of this section is originally sourced from Sergio Pedercini’s Blog. The first step is to add additional ESLint packages that will be used and enforce more strict opinions.

yarn add -D eslint-config-airbnb eslint-config-prettier eslint-plugin-jsx-a11y eslint-plugin-prettier prettier

I prefer the default rules, so I keep the base configuration (which is in package.json), but extend it to allowing for tsx files. The final extends entry ensures that imported TypeScript files are linted correctly.

"eslintConfig": {
  "extends": [
    "react-app",
    "plugin:jsx-a11y/recommended",
    "prettier",
    "prettier/react",
    "airbnb",
    "plugin:import/typescript"
  ],
  "plugins": [
    "jsx-a11y",
    "prettier"
  ],
  "rules": {
    "react/jsx-filename-extension": [
      1, { "extensions": [".js", ".jsx", ".tsx"] }
    ]
  }
}

Next update VS Code settings to ensure linting takes place in the editor. This is done by editing the settings.json inside of VS Code and assuming the ESLint extension is already installed.

"eslint.validate": [
    "javascript",
    "javascriptreact",
    { "language": "typescript", "autoFix": true},
    { "language": "typescriptreact", "autoFix": true}
]

Update Jest targets

For the remainder of unit tests, it is helpful to exclude the Storybook stories and the serviceWorker class from standard test coverage measurements. Add the following to the package.json:

"jest": {
  "collectCoverageFrom": [
    "src/**/*.{js,jsx,ts,tsx}",
    "!src/**/*.stories.{js,jsx,ts,tsx}",
    "!src/serviceWorker.ts"
  ]
}

Until this is no longer accurate

This ecosystem changes at a very rapid pace. I will make an effort to keep this post relatively accurate, but err on the side of more up to date information if you are unsure.

Hello, my name is Ridiculous

Thu, 10 Oct 2019 16:45:00 +0000

One day you find yourself setting up a new greenfield project. Your team needs a service that connects to an upstream account management system to get the active subscription status of a user. Since it only changes daily, to reduce load, the subscription status will be cached in this service. You now are faced with your first decision. Do you name this customer-subscription-cache? Or do you name it yard-lobster?

Defending the Yard Lobster

An argument for the customer-subscription-cache name is that it describes what the service does. Which it does, for about 3 minutes. Two things happen in real life though. The first is that features and requirements change. We may need to add some special case decisions (we always do) and the cache part of the name is now a partial lie. The second is that people organizationally will never refer to it as the customer-subscription-cache, but instead as The CSC. This means you can no longer have a custom-script-compiler or a concurrent-shell-channel.

Eventually, people will refer to The CSC and confuse it with entirely unrelated services because they have no idea what the acronym expands to, but were afraid to ask. Instead, if the name of the service is weird and non-descriptive, like yard-lobster, people feel more comfortable asking what it does until they are sure. In the same vein, the first sentence in the project README is forced to identify what the purpose of the service is. Not compilation instructions, not generic templates, real intention statements.

The Next Generation

As code evolves, it’s entirely common for services to be replaced or combined. This is another great reason for strange names. When one service replaces an older one, there is less ambiguity between the old and the new. Was it customer-subscription-cache or client-subscription-service? Did it merge with the subscription-feature-service? With strange names, it’s a lot clearer what service is going away. They are easier to disambiguate as they evolve, as we have a tendency to anthropomorphize projects that have weird names.

Lean in to the personalities

A positive side effect of falsely assigning personalities to software is that we stop assigning the personalities of the developers. It is common for engineering team members to define communication flow by stating:

Alice receives the request and forwards it to Bob
Bob adds supplementary data and sends logging data to Charlie
Charlie is throwing exceptions all over the place

This is not good for general team health. People get defensive about the systems they work on, since their persona has been associated with it. In the above example, there’s a subtle statement that the instability is somehow Charlie’s fault, even though they only joined the project two weeks ago and inherited this problem service. Instead, the same statement of flow is restated as:

Velvet-Tractor receives the request and forwards it to Stove-Nickel
Stove-Nickel adds the supplementary data and sends logging data to Doll-Hammer
Doll-Hammer is throwing exceptions all over the place

Wait, why is Doll-Hammer acting up again? Charlie, do you need help figuring out why that system is acting strangely?

A note on name sources

A common source for non-descriptive names tends to be pop culture references, including movie quotes or characters. I would highly recommend not using those. The first reason is that a joke from a movie that came out in the 1970s is nowhere near as funny now as you think it is. The second being that as culture evolves, some movies, quotes, and even fanbases become problematic. Just avoid that and go with random word generators. You will get far more interesting results.

Help the people you haven’t met yet

While it may seem more helpful to give descriptive names up front, as organizations grow and leave swaths of archived and abandoned projects the chances of collisions grow. As a new person entering an organization, there are usually blogs, wikis, and source control that compete as sources of definitive information. Since it is all but guaranteed that the search functions for all of these are terrible, trying to determine which authentication-client variant is the one that applies to you, as a new developer, is borderline impossible. So much time is wasted reading about a totally unrelated project. Strange longer names ensure that poor search engines are able to key in on the correct project. Also, forcing people to ask for clarity is a good thing. Just try to make sure the names are over five characters to ensure that overzealous search code will not ignore it.

Developing Cross Browser Extensions

Wed, 25 Sep 2019 17:24:00 +0000

One of the first features requested for Shadowmute was a browser extension to simplify the workflow of generating mailboxes. It was also clear very early on that the usage between Chrome and Firefox users was split fairly equally. The documentation for Firefox and Chrome extension development is extremely well written and detailed, so I’m not going to delve too deep into that. What I would like to write about is how to develop for both at the same time.

Compatibility

When I first started, I aimed for one platform (Chrome) and figured I would use that as a base for the second (Firefox). This created two codebases in the same repo that were almost identical. The biggest difference between the two was the manifest, the second being the location of the runtime (chrome.runtime vs browser.runtime).

It’s worth mentioning the Firefox provides a compatibility layer by aliasing chrome, but I wanted to be explicit in my extensions.

After the initial version was built in chrome it was minutes before it was fully functional in Firefox. The compatibility between the two for a basic extension is extremely impressive.

Packaging

For the most part, packaging is simply zipping up the files representing the extension. Each extension’s code referenced a constants.js file in the background scripts section. The contents of these settings were replaced with production settings during packaging via a python script. Similarly, updates to permissions in the manifest could be applied at the same time.

After the first couple builds, it became apparent that I was reinventing a wheel, and it was simply my lack of experience in the node.js ecosystem. Most of the JavaScript projects I have worked on were either inherited or started with a larger framework, such as create react app. This left a bit of a vacuum in the best way to automate this process in a more JavaScript-ey way.

The Javascript Build Universe

Basic setup

If you are unfamiliar with setting up a javascript project, start by picking a package manager. I chose Yarn, so examples will be more geared that way.

yarn init

This will create your package.json which will function as the overarching index of the ultimate build system you will end up using.

Linting

Linting isn’t absolutely required at this point, but honestly should be set up before building the extension in the first place.

yarn add --dev eslint eslint-config-airbnb-base eslint-plugin-import

This will give you the airbnb base style linting capabilities for your project. I always regret not setting up earlier, no matter when I finally get around to it. Once you have the packages added, update package.json to include a “scripts” section

{
  "name": "semisafe-blog-post",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "devDependencies": {
    "eslint": "^6.4.0",
    "eslint-config-airbnb-base": "^14.0.0",
    "eslint-plugin-import": "^2.18.2"
  },
  "scripts": {
    "lint": "eslint src"
  }
}

In the above example, running yarn run lint will scan the src subdirectory where you can put your actual extension code. This has the added effect of allowing IDEs like VS Code to apply linting with minimal setup.

A detour with Webpack

The first avenue I attempted was to use webpack. It was what I had used in the past for react based development. As the name implies, webpack is more targeted at combining several resources into one processed and minified artifact. This is the opposite of what I was aiming to do

After about an hour of messing around, I decided this was probably not the right tool for my needs.

Building with Gulp

Gulp is another build system for javascript projects. The main process is built around taking a set of source files and piping the results into processing functions. These functions perform operations like concatenation, substitution, and injecting fragments.

yarn add --dev gulp

At the simplest level, the gulp tasks and methods are stored in gulpfile.js in the root directory of your project.

Building the Manifest

The simplest example is building a manifest. Start by identifying the common aspects of the manifest.json required by both extensions in manifests/common.json.

{
  "name": "Semisafe Example Extension",
  "description": "Learning is Fun!",

  "background": {
    "scripts": [
      // In a normal manifest, multiple background scripts could be
      // concatenated, but when packaging here it can be easier to
      // combine them.
      "background.js"
    ]
  },

  "browser_action": {
    "default_title": "Semisafe Title",
    "default_popup": "popup.html",
    "default_icon": {
      "16": "images/icon16.png",
      "32": "images/icon32.png",
      "48": "images/icon48.png",
      "128": "images/icon128.png"
    }
  },

  "manifest_version": 2
}

From there adding the portions of the manifest specific to each browser can be added to manifests/chrome.json (or manifests/firefox.json)

{
  "background": {
    // Chrome requires this explicitly
    "persistent": false
  },

  "permissions": [
    // This is here for a reason,
    // we will substitute it later
    "*://localhost/*",
    "activeTab",
    "declarativeContent",
    "storage",
    "identity",
    "clipboardWrite"
  ]
}

Once these are done, start adding logic to gulpfile.js to assemble a complete manifest. Import some basic required values.

const { src, dest } = require('gulp');
const mergeJson = require('gulp-merge-json');

From there import our build time configurable values. These are sourced from the package.json for the entire project as well as supporting environment variables.

// This is useful for pulling the extension version in from the
// package.json at the root level
const packageDef = require('./package.json');

// Also allow for environment variables that
// don't allow for default in release mode
const envSetting = (varName, defaultValue) => {
  if (process.env[varName]) {
    return process.env[varName];
  }

  if (process.env.ENV !== 'prod') {
    return defaultValue;
  }

  throw new Error(`${varName} is required in prod mode`);
};

Set up the API information based on the runtime values.

// Pull the API server value from an Environment variable
const getApiServer = () => envSetting('API_SERVER', 'http://localhost:9001');

// Define the API server as a manifest permission
const apiServerPermission = () => `${getApiServer()}/*`;

Create a method that accepts browser and destination as parameters. For example, browser would be "chrome" and destination could be "build/chrome".

const buildManifest = (browser, destination) => {
  // Set up manifest values created in code
  const mergeOverride = {
    version: packageDef.version,
    permissions: [
      apiServerPermission(),
    ],
  };

  const fileName = 'manifest.json';

  src([
    './src/manifests/common.json',
    `./src/manifests/${browser}.json`,
  ])
    .pipe(
      mergeJson({
        fileName,
        mergeOverride,
      })
    )
    .pipe(dest(`${destination}/`));
};

The first defined is the mergeOverride, which is a dictionary of overwrite fields.

The src command loads both manifest components explicitly as a stream of files. The stream of file objects is then piped into mergeJson.

The mergeJson operation combines all of the file objects in the stream and squashes them into one file (named manifest.json). The second parameter allows for a programmatic dictionary to be merged in as well. This is helpful inserting the package version. In the case of an array overwrite, such as in permissions, it will replace the first elements and leave the remaining elements as they existed in the files. That is why we made sure the first permission was the external host the extensions would be communicating with.

This operation is a plugin from gulp-merge-json package, which will need to be installed separately by your package manager.

While you may be tempted to just try to implement simple functions in the pipe operations, it is not a standard function call. The operation you’re trying to implement is probably already an existing plugin.

Combining the JavaScript sources

A similar mechanism can be used to combine source scripts. To start we will import more gulp plugins that we have added in via yarn.

const concat = require('gulp-concat');
const inject = require('gulp-inject-string');
const replace = require('gulp-replace');

Create a function that first selects the appropriate runtime parent based on the browser.

const combineSources = (browser, destination) => {
  // This function is just a switch on the browser arg
  const runtime = getRuntime(browser);

  // ... snip

Next create a stream of all files that live in the src/background directory, excluding the one named index.js. We want to hold off on that, as we want to ensure that is the very last file added in the chain.

  // ... snip
  const res = src([
      './src/background/*.js',
      '!**/index.js',
    ])
  // ... snip

Create an in-memory file with the contents of the constants dictionary we want inserted into the code. When we inject it into the stream, we want to prepend it to ensure all subsequent logic has access to those constants.

    // ... snip
    .pipe(inject.prepend(
      `constants = ${JSON.stringify(scriptConstants)};\n\n`,
    ))
    // ... snip

Finally, add the src/background/index.js file we had omitted previously to the file stream.

    // ... snip
    .pipe(src('./src/background/index.js'))
    // ... snip

Transform the stream of multiple file objects into a single element named background.js. The background file is still in the stream, just squashed.

    // ... snip
    .pipe(concat('background.js'))
    // ... snip

Include every other script in our source package for substitutions. We exclude the background scripts that were previously combined as they still exist in this stream.

    // ... snip
    .pipe(src([
      './src/**/*.js',
      '!./src/background/**'
    ]))
    // ... snip

Change all of the extension’s code to use the browser-specific runtime location. I had used __RUNTIME__ in the extension’s code instead of either chrome or browser as it was less likely to collide. Note that this will ruin auto-complete for your IDE.

    // ... snip
    .pipe(replace('__RUNTIME__', runtime))
    // ... snip

With the transformations complete, it is time to gather all the remaining assets in the extension including markup, images and fonts.

    // ... snip
    .pipe(src([
      './src/**/*.html',
      './src/**/*.png',
      './src/**/*.ttf'
    ]))
    // ... snip

The final step is to take the stream of file objects and place them into the correct output directory.

    // ... snip
    .pipe(dest(`${destination}/`));

  return res;
};

Expose the functions

We now have methods to create our manifest, and output the augmented sources. We must expose these tasks in a way for the package manager to call them.

    const outputDir = 'dist';

    const packageExtension = (browser) => {
      const destination = `${outputDir}/${browser}`;
      buildManifest(browser, destination);
      combineSources(browser, destination);
    };

    function chromeTask(cb) {
      packageExtension('chrome');

      cb();
    }

    function firefoxTask(cb) {
      packageExtension('firefox');

      cb();
    }

    exports.chrome = chromeTask;
    exports.firefox = firefoxTask;

These exports allow for two tasks that can be added into the package.json.

"scripts": {
  "firefox": "gulp firefox",
  "chrome": "gulp chrome",
  // ...
}

We can now run the following in the command line:

$ API_SERVER="https://example.com/api" yarn run firefox

Which will assemble Firefox build package with a custom API server.

A larger example

This is a general overview of how cross browser source packages can create an output for each individual browser. As mentioned at the beginning, this was done for the Shadowmute extensions, which are available on GitHub to illustrate a slightly more complex example.

There be dragons

Fri, 13 Sep 2019 17:30:00 +0000

If you have a kitchen, and that kitchen has drawers, there is a roughly 100% chance you have a junk drawer. You know the one, where you store old phone cables, ribbons, safety pins, expired coupons, and a broken red crayon. The software equivalents of these junk drawers take many forms, commonly named Helper, Utils or the worst offender of all.. the TestBase. Join me as we take our new found love of dependency injection, and actually put it to good use.

The dreaded TestBase

This is something that becomes more prevalent above the unit test layer and more common in an integration test layer. At a certain point environmental resources, external state, and other moving parts are going to need to be initialized for tests to validate specific scenarios. After a few methods repeating the same code, the TestBaseOfUnusualSize is created.

It definitely makes sense to minimize code boilerplate when generating tests in the first place, but it comes at a cost of context to later readers. As systems grow and become more complex, different portions will only have partially overlapping resource requirements. Eventually the system ends up with a test base that is this thorny tentacled monster that just works, as long as you don’t look too hard at it.

public class ArcticLairTest extends SuperVillainTestBase {

  @Test
  public void ensureLairKeepsFoodCold() {
    // the provider creation will differ based on your DI framework
    // so we'll hand-wave that away atm
    ArcticLair arcticLair = new ArcticLair(
      mock(TrapDoorContractor.class),
      mock(HvacContractor.class),
      super.foodDeliveryService,
      true
    );

    arcticLair.requestFoodDelivery();
    int atDeliveryTemp = arcticLair.getTemperatureOfFood();
    assertCloseTo(295, atDeliveryTemp);

    arcticLair.timeTravel(1000 * 60 * 60 * 8);

    int secondMeasurement = arcticLair.getTemperatureOfFood();
    assertLessThan(278, atDeliveryTemp);
  }
}

public class SuperVillainTestBase {

  protected UmbrellaSupplier umbrellaSupplier;
  protected HedgeMazeDesigner hedgeMazeDesigner;

  protected FoodDeliveryService foodDeliveryService;

  @Before
  public void setUp() {
    this.umbrellaSupplier = new UmbrellaSupplier(
      400,
      19.43,
      CreditCardProcessor.getInstance()
    );

    this.hedgeMazeDesigner = new HedgeMazeDesigner();
    this.hedgeMazeDesigner.setHedges(Yew.class);
    this.hedgeMazeDesigner.growForest();

    this.foodDeliveryService = new FoodDeliveryService();
    this.foodDeliveryService.addStock(Banana.class, 100);
    this.foodDeliveryService.addStock(Peas.class, 100);
    this.foodDeliveryService.addStock(Pudding.class, 400);
  }
}

Dependency injection has a purpose

This is where dependency injection refactoring will help. Ultimately, these large test bases can be replaced with a module, or several, that define the requirements for a test suite. Instead of spending every test suite run initializing a requirement used by only 5% of unit tests, the module can omit or mock unimportant subsystems. In the previous example we had to wait for a forest to grow for every test suite even though everyone knows a hedge maze in the arctic would be made with Boxwood!

The first step is to realize that the FoodDeliveryService initialization could be done internal to a subclass that lives in the test package.

public StockedFoodDeliveryService() extends FoodDeliveryService {
  @Inject()
  public StockedFoodDeliveryService() {

    this.addStock(Banana.class, 100);
    this.addStock(Peas.class, 100);
    this.addStock(Pudding.class, 400);
  }
}

public class ArcticLairTest {

  public static class Module {
    @Provides
    public FoodDeliveryService(Provider<StockedFoodDeliveryService> provider) {
      provider.get();
    }
  }

  @Test
  public void ensureLairKeepsFoodCold() {
    // the provider creation will differ based on your DI framework
    // so we'll hand-wave that away atm
    ArcticLair arcticLair = new ArcticLair(
      mock(TrapDoorContractor.class),
      mock(HvacContractor.class),
      this.foodDeliveryServiceProvider.get(),
      true
    );

    arcticLair.requestFoodDelivery();
    int atDeliveryTemp = arcticLair.getTemperatureOfFood();
    assertCloseTo(295, atDeliveryTemp);

    arcticLair.timeTravel(1000 * 60 * 60 * 8);

    int secondMeasurement = arcticLair.getTemperatureOfFood();
    assertLessThan(278, atDeliveryTemp);
  }
}

The end of magic

By extracting a reusable FoodDeliveryService subclass, we still have the reusable code from the test base. We have also created a visible area of the test suite that explicitly defines all of the expectations of system state. No more magical setup, and hopefully a reduction in heisenbugs.

Another indicator that this form of refactoring may be applicable is the existence of the @TestOnly annotation. If there is a class that has this feature, could a subclass solve the same requirement? Is the @TestOnly method resetting a singleton’s internal state as opposed to just generating a fresh object graph? Don’t be afraid of test only subclasses, they function as documentation of expected states and allow for more composition friendly test suites.

Removal of @TestOnly methods make for quick, short PRs that can speed up other refactoring tasks. Remember, keep your refactoring changes on the small side for faster reviews and more stable releases.

On returning from outer space

Thu, 05 Sep 2019 18:34:00 +0000

Over the years of my illustrious career, I’ve left several codebases a tattered wreckage. Not intentionally, mind you. Exuberance, eagerness, and a desire to learn new techniques on a slow day all contributed. Half finished implementations of different development techniques littered the landscape. The road to production is paved with good intentions, and a deadline. The code itself worked, shipped, improved but weird vestigial bits floated around. As someone who has fixed as many problems as they have created, you too can larn from my mistaks.

When one encounters and has to regularly work in a codebase that is creaking under the load of it’s implementation details, there are generally three options:

Since everyone is now an expert in dependency injection, we are going to focus on refactoring with an emphasis on dependency injection. The main reason refactoring is worth the attention is it can be done in a minimally disruptive manner. The other reason is that, while lying to yourself about the quality of your code and life is bad, rewriting a codebase is always worse.

It’s worth calling out before diving too deep that just because code is older it’s not necessarily bad. Sometimes the needs of the system change, or the time constraints of the past are not immediately obvious. Be careful of bulldozing through a system that you may have inherited. If you have access to previous authors, they are definitely an invaluable resource on potential pitfalls and any previous efforts towards code cleanup.

But first: tests!

I’m not sure I can put it any more succinctly than Hamlet D’Arcy did, but for the sake of completeness, do not start a refactor without adequate test code coverage. If the codebase you are attempting to clean up does not have reasonable¹ test coverage, this would be a good time to add some. In short: No tests? No refactoring!

Gentle guidelines and exceptional non-rules

Now that we have decided to make the world marginally better and have a safety net of tests to protect us from ourselves, let’s get down to a set of rules that invariably will have exceptions all the time.

Always have a reason

Refactoring for the sole reason of putting your own twist on the codebase is always a bad idea. With each PR generated as part of a refactoring effort, there should be a clear reason behind why a change is being applied. Formatting, linting, opinions, and epic power struggles are not forms of helpful refactoring.

Don’t get attached

Second only to opinionated blog posts, refactoring is probably the lowest positive value endeavor you could provide as a developer. As such, expect your pull requests to be ignored and stomped on by higher priority pull requests. Nothing done as part of a refactor effort should put delivering bug fixes or product features on hold. If the master branch diverges too far from a refactoring PR, throw it away, as the time wasted in merge conflict resolution is rarely worth it.

Progress by 1000 papercuts

Building on the previous two concepts, any attempt at refactoring should result in as small of a pull request as possible. When restructuring class hierarchies, dependencies, and constructor arguments the impact on a codebase ripples very wide, very quickly. By making a concerted effort to change as little as possible in a single pull request, it makes reviews easier and faster. In addition, minimizing the change set reduces the likelihood of getting into a situation where some random class no longer compiles and it becomes impossible to tell which part broke

If you find yourself down a rabbit hole and things are falling apart all around you, simply delete the branch (or start a fresh one) and re-apply the lowest impact changes.

Where do I start?

Just like the guidelines, this is very subjective. A lot of the time there are reasons that code was written a specific way. With that said, as you ease into this, ensure you get eyes on any code you see that feels strange. If you find something was done for performance reasons or something else, your refactoring effort could be just documenting the reasoning for the next reader.

Protect the Object Graph

As you migrate code from a non-DI style to a DI style, you should be looking for places where the object graph is broken. As you will recall, any time an injectable instantiates an internal class as a newable, the object graph breaks. If you notice a singleton being passed around directly, or another class passed in solely to be used to instantiate a child class these are good indicators that the object graph was broken too early.

public class SuperVillainLair {
  private final NuclearReactor reactor;

  public SuperVillainLair(AtomicClock atomicClock) {
    // The lair does not need a clock, this is a sign the clock should have
    // been injected
    this.reactor = new NuclearReactor(atomicClock);
  }
}

The best approach to this is to trace the call references backwards to find a single point where the object graph first broke:

public class SuperVillainRealtyGroup {
  private final List<SuperVillainLair> lairs;

  public SuperVillainRealtyGroup(int lairCount, AtomicClock atomicClock) {
    List<SuperVillainLair> lairs = new ArrayList<>();

    for (int i=0; i < lairCount; i++) {
      lairs.add(new SuperVillainLair(atomicClock));
    }
  }
}

Phase 1:

In the first pass, we move construction of the SuperVillainRealtyGroup into a Factory to allow it to be provided automatically by the injection framework.

public class SuperVillainRealtyGroup {
  private final List<SuperVillainLair> lairs;

  public static class Factory {
    private final AtomicClock atomicClock;

    @Inject
    public Factory(AtomicClock atomicClock) {
      this.atomicClock = atomicClock;
    }

    public SuperVillainRealtyGroup create(int lairCount) {
      // Note: the object graph is still broken here, but this
      // gives us an controlled point to re-attach later
      return new SuperVillainRealtyGroup(lairCount, atomicClock);
    }
  }

  private SuperVillainRealtyGroup(int lairCount, AtomicClock atomicClock) {
    List<SuperVillainLair> lairs = new ArrayList<>();

    for (int i=0; i < lairCount; i++) {
      lairs.add(new SuperVillainLair(atomicClock));
    }
  }
}

After this has changed we consult our peers, get it approved with the note that it is rebuilding the object graph and merge forward. Once again, never try to do too many changes in one pass, otherwise the review is tedious and can lead to a spiral of changes that nobody can track.

Also worth reminding is that we did not change the original target of SuperVillainLair as there could be several other classes that instantiate it.

Phase 1.n

Now that the SuperVillainRealtyGroup is an injectable, we will update all other classes that instantiate a SuperVillainLair as a newable to ensure they are all injectables themselves, one at a time.

Phase 2

It is now safe to update the SuperVillainLair class to become an injectable. Since the previous phase guaranteed that all places it was instantiated were called from an injectable, the change can be propagated up one level and still be very readable².

public class SuperVillainLair {
  private final NuclearReactor reactor;

  @Inject
  public SuperVillainLair(AtomicClock atomicClock) {
    // Once all classes that instantiate NuclearReactor are updated
    // this can go away
    this.reactor = new NuclearReactor(atomicClock);
  }

  // This is optional to allow for partial application of the new
  // injectable construction. However, if the code is tangled up
  // to the point where a single constructor can't be changed cleanly
  // you may want to refactor the blocking area elsewhere in the code
  // and save this for later
  @Deprecated
  public SuperVillainLair(AtomicClock atomicClock) {
    // The lair does not need a clock, this is a sign the clock should have
    // been injected
    this.reactor = new NuclearReactor(atomicClock);
  }
}

public class SuperVillainRealtyGroup {
  private final List<SuperVillainLair> lairs;

  public static class Factory {
    private final Provider<SuperVillainLair> superVillainLairProvider;

    @Inject
    public Factory(Provider<SuperVillainLair> superVillainLairProvider) {
      this.superVillainLairProvider = superVillainLairProvider;
    }

    public SuperVillainRealtyGroup create(int lairCount) {
      // The object graph has now been fixed
      return new SuperVillainRealtyGroup(lairCount, superVillainLairProvider);
    }
  }

  private SuperVillainRealtyGroup(int lairCount, Provider<SuperVillainLair> superVillainLairProvider) {
    List<SuperVillainLair> lairs = new ArrayList<>();

    for (int i=0; i < lairCount; i++) {
      lairs.add(superVillainLairProvider.get());
    }
  }
}

Phase 3

Now that the object graph has been repaired, we can make the minor change to NuclearReactor and push that up one level as well. If it turns out there was another class that instantiated a newable NuclearReactor, don’t try to squish it together. Reset and repeat phase 1 & 2 as needed.

public class SuperVillainLair {
  private final NuclearReactor reactor;

  @Inject
  public SuperVillainLair(Provider<NuclearReactor> nuclearReactorProvider) {
    this.reactor = nuclearReactorProvider.get();
  }
}

public class NuclearReactor {
  private final AtomicClock atomicClock;

  @Inject
  public NuclearReactor(AtomicClock atomicClock) {
    this.atomicClock = atomicClock;
  }
}

Commit. Commit. Commit.

I’m going to stress it again, make these changes as small as possible when pushing for review. Larger changes in an active codebase will create more merge conflicts, as the class hierarchy is changing in a pretty drastic way overall. This not only affects the developer working on the refactor, but every other teammate that has work in progress. The goal here is to make everyone’s life easier, not to ensure they have good merge skills.

Anonymous Classes

One common time sink when it comes to refactoring to repair an object graph is anonymous classes. Here is s normal example using an anonymous class:

public class Wrapper {

  Map<String, String> parentClassLookupTable;

  private void sendEnclosedEvent(Map<String, String> lookupTable) {
    // ... snip ...
  }

  public void makeInternalTimer() {
    Timer timer = new Timer();

    timer.schedule(new TimerTask() {
      @Override
      public void run() {
        sendEnclosedEvent(parentClassLookupTable);
      }
    }, 1000);
  }
}

This is a very clear and concise use for an anonymous class. Testing that Timer calls run() correctly adds no value to our code, and the enclosedEvent() call may need access to some internal state.

We run into a problem when the object graph is required in any way by operations inside of sendEnclosedEvent(). This is really the same problem as before, we have broken the object graph. In this case, it’s a very trivial example and can be worked around. In reality, this can get more twisted and complex. When untangling, anonymous classes are fairly good candidates to get extracted for clarity. Hours can be wasted tracking down a non-obvious compile error when you are stuck inside of an anonymous inner class.

Like other refactoring exercises, a class extraction of any kind should exist as its own pull request with only fixes to tests included. Tracking other changes during a review can be very difficult and prone to turning into an unhelpful rubber stamp.

And stick the landing

Cleaning up and modernizing a codebase can be cathartic but it can also turn into a giant time sink if you’re not careful. Just remember, if you approach it in short discardable bursts you can get more done over time with the least amount of disruption to the forward momentum of bug fixes and feature development.

“Reasonable” is obviously at your team’s discretion, but it should be far higher than zero. ↩
I waver back and forth on the use of @Deprecated as opposed to a commit that just sweepingly cleans house. If @Deprecated actually supported attaching a reason as an argument, I’d probably feel better. ↩