An Inconvenient API

Imagine that you’re working on an unreleased project, and you discover a need to extend one of your custom types. There’s some complex initialization required before methods will work properly.

You end up with client code that looks like this in C#:

var operation = new ImportOperation();
operation.Initialize(client)

or like this in Go:

var operation ImportOperation
operation.Initialize(client)

You realize that the API isn’t perfect, so you decide to document the requirement for Initialize() to be called, and move on.

That’s enough, right?

Well, no.

You’ve forgotten that while documentation is important as a reference, by and large people don’t read documentation unless something has gone wrong. This isn’t because they’re bad people; it’s because they’re focusing on the goal they want to achieve - and that goal probably doesn’t include putting on some soft jazz music and sitting down on a cold winters night with a cup of cocoa in front of a blazing fire to read 20k words of documentation.

How should we modify this API so that our users simply can’t get things wrong in the first place?

If we can find a way to do this, not only do we make things much simpler for anyone consuming our code, but we now have less documentation to write as well.