Since I have two young kids at home I probably spend more time reading now than I've done since school. Over the holidays I spent a bunch of time reading, and as usual I try to read a book for myself after the bedtime stories!

One of the books I really enjoyed was A Philosophy of Software Design by John Ousterhout. This book is probably one of the most recommended reads I see related to designing great software overall, and since most engineers have read Clean Code I clearly understand why.

I have some thoughts on Clean Code and while I have many thoughts on this book as well, I'd like to focus on one thing that sticks out as key to me.

Complexity collects at boundaries

We can easily see this time and time again. We get sloppy with designing the interface of some module and expose internals that should stay internal. We change some implementation detail in that module over time and all of the sudden we either refactor the consumers as well, or we have to keep a leaky abstraction alive by working around a poorly designed interface.

A very simplistic view of an application, in one way or another inside most companies I've been at) basically flows like this:

  • HTTP Layer deals with de/serialization
  • Some "orchestration" layer deals with the business logic. Utilizes clients of different kinds (DB, HTTP) to apply logic to data.
  • Clients act as an abstraction for the implementation details of how data is being collected.

Commonly these clients start leaking, most of the time because the same developer would write the client and implement its usage in a service.

The best modules are those that provide powerful functionality yet have simple interfaces.

Personally I think a solid way to look at making an interface simple is just:

Does a consumer really need to know about this?

Do you really need to expose a retry timer in your productClient? Should you really force a consumer to state how many items per page your paginated response sends?

What are the things you really can't (or shouldn't) handle by default?

Maybe you should consider writing an API for things before you implement? ;) At least that way we can guarantee you will not know all the details yetI!

Out.