Don't make it hard to trust your code

I recently learned that an API I had been using for a project was lying to me. Maybe not intentionally but anyway. I think that a fundamental rule in software development is that you must trust that the methods you call at least try to do what they say they do. For example if a method is called "SavePerson" I should assume that it will save a person and nothing else except maybe some logging. If the method is called "SavePersonAsync" it should be safe to assume that it will be an asynchronous operation and that it will not block my execution. And if the method takes a callback method I think it should be safe to assume that it is an asynchronous operation and that it will not block my execution.

Well in my case the API I was using had a method that took a callback function as an argument. But it turned out that the method would connect synchronously and then perform the operation I requested asynchronously. So what do you think happened when the component couldn't connect? You guessed right! It blocked my execution on a thread where I assumed I did not do anything blocking causing big performance problems!

It doesn't matter if you document this. The most important documentation you have is your method name and the patterns you use. In my opinion if something takes a callback then it is non-blocking!

Comments

• Anonymous
  June 13, 2013
  Everyone should read Framework API design by Krzysztof Cwalina.