reviewing-abstraction-boundaries

Reviewing Abstraction Boundaries

Overview

Identify where internal implementation details have leaked through to the public surface of a project. The goal: your users should never need to know or care which libraries, engines, or data structures you use internally.

Core principle: If you can't swap an internal dependency without changing something your users touch, you've found a leaked abstraction.

When to Use

• Naming a new file format, config key, CLI flag, or API field
• Reviewing a project's public surface before a release
• Choosing conventions that users will build around (template extensions, config schemas, plugin interfaces)
• After adding a new dependency that surfaces in user-facing areas
• When a dependency is deprecated or you're considering alternatives

The Substitution Test

For each public surface, ask:

If I replaced [internal dependency] with a different one, would my users need to change anything?

If yes, you've found a leak. The severity depends on how many users are affected and how hard migration would be.

Where to Look

Surface	Example leak	What it should be
File extensions	.tera (exposes template engine)	.die (project's own concept)
Config keys	jinja_options	template_options
CLI flags	--postgres-host	--db-host
Error messages	"Tera syntax error on line 5"	"Template syntax error on line 5"
API responses	{"orm_id": 42}	{"id": 42}
Directory names	migrations/diesel/	migrations/
Environment vars	REDIS_URL (when it's "the cache")	CACHE_URL
Documentation	"Uses Jinja2 syntax" (when engine could change)	"Uses template syntax (powered by Jinja2)"

Not every mention of a dependency is a leak. REDIS_URL is fine if Redis is a deliberate, user-chosen infrastructure component. It's a leak when Redis is an implementation detail of your caching layer that users shouldn't need to know about.

Severity Triage

Fix now (high blast radius, grows over time):

• File extensions and formats users create many of
• Config keys in files users commit to repos
• Plugin/template interfaces others build against

Fix soon (moderate blast radius):

• CLI flags and environment variables
• Error messages users see regularly
• API response field names

Note for later (low blast radius):

• Internal directory structure
• Log messages
• Transient error details

The key factor: how many instances accumulate over time? A config key is set once. A file extension is used on every template file in every template repo. The file extension is more urgent.

When You Find a Leak

1. Assess migration cost now vs. later. The earlier you fix it, the fewer things break. One template repo with .tera files is easy. A thousand is a migration project.
2. Choose your own name. Pick something that belongs to your project's domain, not to any dependency.
3. Soft-migrate if users already depend on it. Auto-detect the old convention, fall back gracefully, emit a deprecation warning with clear migration instructions.
4. Give an escape hatch. Let users explicitly opt in to the old behavior so nothing breaks silently.

Common Mistakes

• Over-abstracting. Not every dependency name is a leak. If the user chose the dependency (e.g., picking Postgres as their database), naming it directly is fine. Abstract only what's your implementation detail.
• Abstracting too late. Once an ecosystem builds around a leaked name, the migration cost may exceed the benefit. Catch leaks before they accumulate.
• Renaming without migration. A hard break with no fallback punishes early adopters. Always provide a deprecation path.