The Importance of Good Interfaces

Author: Szymon Lipiński
Published at: 2017-01-18

A Short Introduction To A Good Interface

When you are using some class, function, library, you have use its interface. Interface is the set of public knobs, and switches which you can use. Usually the interface for most of the libraries, functions, and classes has one common feature: it irritates programmers.

The Main Pains When Using an Interface

  • lack of documentation (or even worse: wrong, misleading, not updated documentation)
  • crazy logic for doing simple things (like: let’s create hundreds of objects to create other objects, to insert proper types to a function, which in fact adds two integers)
  • lack of sensible naming convention (so you remember the function name, and you have no idea how to write it) [also described here][1]
  • huge incompatibility with the previous version (so now you need to spend days changing you program due to some undocumented things)

The Great Interface

On the other hand, what can be the main good points for making a great interface?

  • great documentation
  • simple logic for doing complicated things (the most complicated things should be hidden behind as simple as possible classes, and functions)
  • good naming convention (this means two things: you should use the one that is common in your language community, and should be consistent in the whole library)
  • the compatibility thing is hard sometimes, breaking compatibility is sometimes needed, but this requires great documentation, so programmers won’t be surprised

In this post I will concentrate only on the incompatibility problem, which can be avoided very often, just because you think about it a little bit earlier.

Thinking and Experience Isn’t Overrated

Yea, I know, there is the great quote repeated endlessly by the programmers who cannot read:

premature optimization is the root of all evil (or at least most of it) in programming

If you can read, take that book, and check what is written a couple of pages later. Or use wikiquotes if you wish.

This is not about not optimizing the things.
This is about knowing when to optimize to get the biggest impact on the overall efficiency.