Amateurs talk implementation; professionals talk interfaces

There’s an interesting quote that is often credited to Omar Bradley (1893-1981), the last five-star officer of the United States. It goes like this:

“Amateurs talk about strategy and tactics. Professionals talk about logistics and sustainability in warfare” (Omar Bradley)

I think the main idea around this quote is that amateurs often get caught up in discussing strategy and tactics. They fail to realize the bigger problem is logistics; getting their soldiers to the front-lines, building bridges to support troop movements, supplying their armies with food and medicine, etc.

The basic sentiment about discussing an interesting problem but giving less attention to the more important problem can be applied to many types of decision-making.

I’d like to propose a similar statement about software engineering:

“Amateurs talk about implementation. Professionals talk about interfaces”

Developers often get caught up too much in implementations. They may discuss the internal code of a class or function in detail.

However, the problem that needs more focus and attention is the interfaces between modules. There’s a few reasons apis deserve much more attention than they currently get:

1. Apis are much harder to change than implementations.

There are entire release and versioning processes that only exist because apis are hard to change.

For example, maybe you decide that you want to change the name of a field in a REST api. You likely need to create a brand new major version to prevent breaking api consumers. But you probably want to support both v1 and v2, so you need to keep around the old code for a while and set a deprecation notice for v1.

Another example: suppose you maintain an internal library of react components. You decide that the name of a component doesn’t make sense anymore, so you want to change it. You likely need to bump the major version, update the CHANGELOG, and publish a new version.

With all the overhead that is required, api changes like this in practice are often not done, even if it would help with readability or maintainability. Compared to these challenges, refactoring an implementation is a breeze. Want to change the name of a local variable? It takes about half a second.

2. The readability of your code highly depends on crisp and simple apis.

Take any piece of code and most of what it is doing is interacting with other modules, classes, or functions via their apis. If the apis of these components are not straightforward, it will pollute the readability of everywhere they are used. This pollution can quickly spread to the rest of the codebase and become very hard to change.

Some of this might seem obvious, but it’s worth stating explicitly. I often try to think critically about my api design and only afterwards do I worry about the implementation.