Shower Thoughts: Everything’s an API

Pseudo random opinions on code quality and elegance that popped in my mind on a Sunday morning rumination in shower, before my morning tea. So pinch of salt and all.

Courtesy: Walmart

Everything is an API

The word API conjures up images of REST based HTTP URIs (or gRPC for the cooler kids) for most people. In this context I refer to API it at a much deeper sense. Treating any and every component (class, function, interface etc.) of a system as a user interface with helps reducing complexity. The users in this case are other programmers.

The interface’s sole responsibility is to provide the consumer with a functionality with minimum details of ‘How’, aka encapsulation and abstraction. As an analogy, GMail users don’t need to know ‘How’’ the login screen works, just `What` it does. This is a simple but powerful concept and applies at all levels in the software stack (from individual classes in a service to aggregates in a complex microservices architecture to GUIs). Let’s take an example, say of a Library.

The questions we should ask here are:
1. What the library class needs to do right now, without making any assumptions?
2. What the consumer of the class needs to know?
3. What’s the least data that can be shared with consumers?

A simplified version of the Library class above does the following:

a. Removes setters that might override state of a class. It’s always safer to assume there need not be any setters
b. Renames the method to addBookto only expose what needs to be done and not how. Internally it can be a list or a set or a queue or a banana.
c. If there are any behaviour based interfaces, an entity can implement them. e.g. A Book is Issuable
d. Marks the constructor parameter as val to make it immutable. (Yep, immutability is good)

Cognitive (over) load

It’s easy to get lost in the labyrinth of a complex code base. The impact is tired and overwhelmed programmers. In my opinion, the primary imperative of all the ‘Clean Code’ recipes is to reduce the amount of code a programmer needs to hold in their mental cache. Smaller the cognitive load, better the code and the overall software. God Objects are the biggest source of errors and loss of productivity

KISS > DRY

As programmers we obsess on code deduplication. It’s a noble intention, but sometimes to maintain sane abstractions it’s OK to violate DRY. I can’t explain it better than Sandy Metz does.

Tests

Programmers tend to be up in arms to either condemn or extol TDD, but one idea most programmers agree with is writing tests (before, during or after). As much as possible, tests should validate the ‘What’ rather than ‘How’ or ‘When’. But it’s trickier than it seems. e.g. Ruby, Java etc. ruby makes it very easy to test the code structure, and Ruby being, well a banana republic of programming languages, necessitates validating the structure sometimes. More robust languages (aka strongly typed) obviate such testing.