loading...

Maintaining an Internal Library: Learning What I Thought I Already Knew

hdennen profile image Harry Dennen Originally published at Medium on ・3 min read

http://www.smbc-comics.com/?id=2475

The product I work on needed to support window messaging with some company specific standards so I thought it would be nice to separate the transport from the main system entirely. That way we could give it to our customers to ease integration and use it in our other products to coerce a single standard.

Also, it was also something I could experiment on without ten other devs pushing commits. 😅

As it matured from a single file to a full library with a build / release / deployment pipeline I bumped into some less obvious whys behind development best practices. Here they are.

Branching Strategy (gitflow)

It is only faster to smash out commits on master if you ignore all the time costs that are not writing code.

We know these to be true: You will change your mind. You will make mistakes. You will forget things. You will make poor decisions.

The cost of these things is not just the backtracking and amending process, it is just as much if not more the building of mental context necessary to backtrack and amend.

Put a timer on the next time you take a week away from some code and see how long it takes to get back into that head space.

Of the many, many benefits of gitflow, I found this to be the biggest time saver: Well kept branches keep mental context cordoned off and cohesive. If the branch has too many conceptual changes in it, the benefit goes away. One idea, one branch.

Updating a library is easy, updating dependency chains is not.

We have a small helper library we ship which depends on my library, it also includes a demo site that needs to have the latest version. Our main client also depends on my library, and there is a partner repo that stores the helper library for live pickup. Simple. 😐

Each of those external facing codebases are subject to a release process.

It did not take long to discover that if coordination is key, then Automation is cornerstone. Maybe it’s just me, but having more than a couple moving parts to coordinate meant that I almost always forgot some small piece.

Also, a good project manager is worth their weight in gold.

Standard Version is Great!

Honestly, spitting out an auto generated changelog with version bumping and a nice chore commit is fantastic. We already follow Angular commit guidelines on my main project so this was an easy transition. It’s not so practical on our main project due to the sheer volume of commits, but it sparks joy for this smaller stuff.

UNIT TESTS

I have never been able to maintain TDD for very long. I am honestly not entirely sure it is a practical approach to modern JS applications. That said, well considered unit tests are 100% absolutely necessary.

Well considered is the operative phrase here. We’ve all seen high coverage of unit tests that effectively test nothing. What I am talking about are tests that ensure a given public method is going to perform as expected under any state conditions. The easiest way to achieve this: use unary pure functions. Wrangle some state into an object, pass it to the function, get a return value. Test the wrangling; test the return.

There are many other ways to assemble and test code. In my experience this is the simplest and most maintainable. And at the very least it will encourage you to abide by the Law of Demeter.

Discussion

pic
Editor guide