The API designer is sometimes to blame, in my experience. A good example of this is in modern programming is the Android API which is often surprisingly horrib

The API designer is sometimes to blame, in my experience. A good example of this is in modern programming is the Android API which is often surprisingly horrible and basically requires reading the API implementation source code (and maybe even the source code of multiple different versions since they will behave differently) to fully understand things that should be relatively simple concepts, like how to properly retain state across a device rotation when using fragments without getting yourself into an exception-raising "Illegal State". Note: I'm not asking for a reference on how to do this specific thing, I actually know it really well, it is just that the amount I had to learn about the internals of how everything worked to get to that point is completely unreasonable relative to how simple it would be if the API were better designed.