💾 Archived View for space.matthewphillips.info › posts › high-level-maintainability captured on 2024-07-08 at 23:50:47. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

High-Level Features Are Mostly About Maintainability

The topic of low-level vs. high-level comes up a lot in API design. It seems, though, that we rarely define what it is; what we mean by these terms. There's a vague understanding we all share, something to the level of "low-level means you need to type more" or "high-level is easier", and those are all true.

What's a little more clear is the purpose of these different levels. For low-level the purpose is about providing maximum flexibility, the ability to find common "shapes" among different ideas, allowing them to be glued together, and to provide room for experimentation.

For high-level, it's often simplied to be about ease-of-use. Writing less code. Not needing to understand gory details. But I think this outlook gets it wrong. High-level features are mostly about maintainability. Most things developers ask for, are things that will make it easier to get code reuse in their project. It's not to simplify the implementation of some feature. A feature you implement once is maintainable. Having to do very similar things many times, or needing to pick between one of hundreds of similar libraries that do the same thing in slightly different ways.

Here's a couple of examples:

Pull-to-refresh is a common UI paradigm on mobile. Implementing this is a huge pain on the web.
Templating, broadly speaking, is a way to define how HTML should look given some data as input.

The first is about ease of use. A high-level API would make creating this type of UI much easier. But your code would not be more maintainable for it, outside of there just being less of it.

The latter is about maintainability. Templating makes it so you don't have to think about the rigid details of turning existing DOM into a new representation. As a result it's easier to maintain and keep up to date with changing requirements.

What do developers talk about mostly? They talk about templating. Over and over again. They talk about it probably 10x as much as any other single topic. The next most talked about topic is probably styling. And specifically, about styling patterns to improve maintainability.

This may be an arbitrary example, but I think it holds. Find me a high-level API that's frequently discussed, that is not about maintainability, and I'll eat my shoe.