(Image: Poetry. Compression done well. “The Universe in Verse: 15 Portals to Wonder through Science and Poetry” by Maria Popova)
Here’s the dirty secret of platform engineering: you’re not building code; you’re building shortcuts for other people’s brains. You are in the business of cognitive offloading. That’s the job. That’s the glory. That’s the trap.
“First learn the meaning of what you say, and then speak.” — Epictetus
When a developer reaches for your platform, they’re saying: “Please, take this mess away so I can think about what actually matters.” If you succeed, their world gets lighter. If you fail, you’ve just wrapped their burden in barbed wire.
“compression produces fragility dressed as cleverness”
The temptation is to compress. To shove complexity into a smaller space and call it “elegant.” But compression isn’t abstraction. Compression is what happens when you cram too much into too little and hope no one notices the bulge. Richard P. Gabriel warned us about this—compression produces fragility dressed as cleverness.
Good abstraction, on the other hand, is composition: building blocks that can be trusted, reused, and recombined safely. Think of Spring’s JdbcTemplate. It doesn’t pretend SQL doesn’t exist. It doesn’t crush reality into a shapeless blob. It simply removes the boilerplate of error handling and resource cleanup so you can focus on your queries. That’s cognitive offloading. That’s trust.
So remember: you’re not here to show off compression tricks. You’re here to create solid ground. Reuse demands safety, and safety demands trust. Trust comes from building foundations that won’t ripple under your users’ feet.
In platform engineering, aim for abstraction that offloads cognitive load, not compression that hides danger. Composition beats subclassing; reuse requires trust; and trust is born from safety, not cleverness.
Aphorism
Build abstractions, not compression.
Rationale
Abstractions reduce mental load and enable safe reuse. Compression only hides complexity, making it harder to trust, extend, or repair.
Some Practices
Cognitive offloading in platform engineering can take many forms:
Boilerplate removal: JDBC templates, ORM mappers, API scaffolding tools.
Convention over configuration: frameworks like Rails or Spring Boot reduce “decision fatigue.”
Caching & memoization: save developers from repeating expensive operations.
Sensibly opinionated defaults: secure-by-default authentication, logging, and metrics.
Guardrails: APIs and tools that prevent unsafe actions without being tyrannical.
Automation: pipelines that take care of build, test, deploy, and rollback.
Shared vocabulary: domain-specific libraries that give names to repeated patterns.
Self-service documentation: so the platform explains itself, not you explaining it.
Each of these offloads thinking without erasing the domain’s reality. That’s the difference between abstraction and compression.
Some Pitfalls
Over-compressing domains until they’re unrecognisable.
Subclassing hierarchies that collapse under change.
Building “magic” that hides risk instead of surfacing it.
Some Checklists
Does this abstraction make the developer think less, not more?
Can it be reused safely in different contexts?
Is failure understandable and recoverable?
Some Examples in Code
Bad Compression: Subclassing Trap**
// Over-compressed: tries to hide SQL completely
public class UserRepository extends SqlConnection {
public User findUserById(int id) {
String sql = "SELECT * FROM users WHERE id = " + id;
return executeAndParse(sql);
// "Magic" hidden in the parent class
}
}
// Fragile: SQL is a string mess, error handling is invisible,
// and extension means breaking the parent’s brittle guts.Good Abstraction: Spring’s JdbcTemplate
@Autowired
private JdbcTemplate jdbcTemplate;
public User findUserById(int id) {
return jdbcTemplate.queryForObject(
"SELECT * FROM users WHERE id = ?",
new Object[]{id},
(rs, rowNum) -> new User(
rs.getInt("id"),
rs.getString("name"),
rs.getString("email")
)
);
}
// Clear, safe, reusable: the boilerplate of managing connections,
// statements, and exceptions is gone, but SQL and domain logic remain visible.Pitfalls: When Compression Eats Itself
Focus on reuse through safe, composable abstractions
Years ago, a team I worked with built a platform wrapper around cloud storage. They wanted to “simplify” things, so they compressed the entire S3 API into about five methods. No buckets, no permissions, no metadata—just upload(), download(), delete().
It worked great in the demo. Everyone clapped.
Then real users arrived. Someone needed object versioning. Someone else needed lifecycle policies. Another team needed signed URLs. Each time, the wrapper broke. We were forced to either tear it apart or bolt on hacks. Pretty soon, the “simple” abstraction was more complex than the thing it tried to hide.
The root problem? Compression instead of abstraction. By hiding S3’s reality, the platform denied developers the details they actually needed. The trust was gone. Users started bypassing the wrapper and calling S3 directly, which meant we now had two inconsistent worlds.
The lesson: if you compress, you will be eaten alive by reality. If you abstract carefully, you give developers solid ground without denying them the horizon.
Focus on reuse through safe, composable abstractions; avoid compression disguised as elegance. Simplify everything, hide nothing.
Further Reading
- Richard Gabriel, Patterns of Software (on compression vs abstraction)
If you enjoyed this entry in the Software Engineering Enchiridion then you might also enjoy:
