So I Wrote a Library

If you’ve never done it, go out and find an open source project to contribute to. Whether it’s one of your own, or something you use, go and try writing code in the wide open to see how it feels.

I’ve recently been working on a library of my own. I say my own. It’s actually someone else’s code that I produced a deep fork of. The resulting version would have a terrifying number of diffs with the original, because I did a complete rethink on how the original operated and went to town on applying this rethink.

Before you say anything, I agree: this is not the usual way to do open source.

The library is called System Stubs and is hosted on GitHub, published via Maven Central, and I even wrote a guest article about it on Baeldung. (I should point out that I didn’t get special privileges there because I’m an editor… I had to go through the usual editorial process and was not paid to write about my own work!)

This isn’t the first open source Java Unit Testing contribution I’ve made, and it probably won’t be the last.

How Did it Happen?

The ideal open source contribution goes like this:

  • I raise an issue with a question/problem
  • The owners reply with advice or encouragement to fix it
  • Or nobody says anything, so I decide to go and try to fix it myself
  • A PR is raised, with the expectation that it’s doing some good
  • There’s a review process in which the owners of the project help fine tune, or kindly decline the request

I started down that road with the original project on which System Stubs was based. The author of the project, for reasons that I won’t debate, felt that the direction was against what they had set out to do. They agreed I could rewrite their code if I wanted. As they published under the MIT Licence, I don’t think I really needed their agreement, but it was nice to have encouragement.

What Is The Difference of Opinion?

There are a few stylistic differences between the library I ended up with and the one I started with. Quick history lesson:

  • System Rules was a JUnit 4 plugin for controlling environment variables and other system resources during tests
  • It wasn’t compatible with JUnit 5 (though I had some workarounds for some use cases)
  • The author decided to stop being bound to a particular JUnit implementation and produced System Lambda, which just works by wrapping around test code within a method
  • The author decided to remove all the public classes and build a facade with various recipes for setting up different sorts of tests

This resulted in an intentional opaque monolith that could only be used one way.

A good way!

Seriously – there are fewer headaches if you just constrain what the user can do to a few sensible things.

However…

It turns out that the approach above works well for 80% of tests where there’s limited repetition between test cases… but those 20% it doesn’t cover are the ones where it’s probably most awkward to do it any other way! In my view.

Similarly, a lot of test code can be very very long-winded as it sets up test data etc. There are various ergonomic tricks I’d added to my local subclasses of the original System Rules that I really wanted to have access to again.

Politely producing my own opinion on this library in parallel to the original, was my way of supporting the alternative perspective. I even made sure that my library was cross compatible with the original, so migration from System Lambda to System Stubs (though clearly not the other way) was relatively frictionless.

Open Source definitely allows different schools of thought to co-exist without rancour.

What Does it Feel Like?

Writing code for others to consume feels like your every move is going to be scrutinized by someone else. That your bad designs will annoy someone, and that every public interface you create will be set in stone forever, in case someone’s using it.

I think it creates a tendency to overthink and over engineer, and I also think it makes you dig deeper to consider more edge cases for testing.

It’s a humbling experience (if done properly) and very edifying. Similarly, by trying to write the sort of documentation that will avoid users raising loads of questions and issues, you learn even more about your own software.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s