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();

or like this in Go:

var operation ImportOperation

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.


blog comments powered by Disqus
Next Post
Using Constructors  27 Feb 2023
Prior Post
Method Archetypes  11 Sep 2022
Related Posts
Browsers and WSL  31 Mar 2024
Factory methods and functions  05 Mar 2023
Using Constructors  27 Feb 2023
Method Archetypes  11 Sep 2022
A bash puzzle, solved  02 Jul 2022
A bash puzzle  25 Jun 2022
Improve your troubleshooting by aggregating errors  11 Jun 2022
Improve your troubleshooting by wrapping errors  28 May 2022
Keep your promises  14 May 2022
When are you done?  18 Apr 2022
February 2023