Naming things is hard.
Usually when we are going to have a brand new kid, naming her/him takes a couple of months. The endless discussions, sleepless nights, all the lists of possibile combinations of letters. And all the effort just to achieve something that would sound nice to us. And only to us, as usually the grandparents of that brand new guy will not be happy with our choice.
The normal baby delivery date is quite far in the future, so usually we have lots of time to think about this name, and the possible problems the kid will have when naming like Donald Trump Otieno or like this:
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
- 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.
The requests is quite a good library, it simplifies using the ugly and terrible standard Python HTTP libraries. Today I found a much nicer interface even to the requests itself.