Skip to main content

Pragmatic developers guide to river crossing

TODOs, FIXMEs, issue links, and hacks are terms in a codebase that get the blood boiling for some, but I am almost always glad when I see them nowadays. The terms have saved me from ghost chases more times than I want to know. My thoughts on the matter are best explained by this little tale.

Let's imagine a dev team tasked with figuring out a way to transport a wolf, goat, and cabbage across a river. They have been contracted by a client expert in transport systems

After a discussion with the domain specialists, the developers conclude that renting a boat for the river crossing is the way to go since it is the most cost-effective. 

The transportation design is abstracted with an open-source library. Perfect! Such an easy job, right? Provided, of course, that the library API is decent.

It turns out the library, although simple, could be better. It is imperative, stateful, and cumbersome—very outdated stuff. There are fortunately, only three public functions, init, load and moveToNextBank. The library needs to be initialized with the transported items while load takes an index of an element in said item array. One transported thing at a time, weird!

They start with this code.

const animals = ['wolf', 'goat', 'cabbage']
boat.init(animals)
boat.load(animals[0])
boat.moveToNext()
boat.moveToNext()
//The next step is to load the cabbage
boat.load(animals[2])
// Crash!
view raw first.js hosted with ❤ by GitHub

But when they run the program, they get an index out-of-bounds error. The baffled developers tear their hair and try to figure out what is happening.

After some trial and error, they realize that the payload array loses the last index if the wolf is moved first. Bizarrely, they notice that if they carry the cabbage first, the middle index (goat) disappears from the boat state. 

After hours and hours of brute force hacking, they figure out a bunch of edge cases that corrupt the library's initial state. Working around the bugs, they write the following code successfully transporting the payload.

function transfer() {
boat.initialize(animals)
boat.load(1)
boat.moveToNextBank()
boat.unload()
boat.moveToNextBank()
boat.load(0)
boat.moveToNextBank()
boat.unload()
boat.load(1)
boat.moveToNextBank()
boat.unload()
boat.load(2)
boat.moveToNextBank()
boat.unload()
boat.moveToNextBank();
boat.load(1)
boat.moveToNextBank()
boat.unload()
}
view raw working-solution.js hosted with ❤ by GitHub

Job done! They check the code and move to the next assignment.

🤔

We can do better! Let's rewind to the beginning.

In an alternate timeline, as the team taking the task notices the library quirks, they search the internet for alternatives to the transport library and unfortunately discover none. Accepting the fact and given the time pressure, they reluctantly stick to it.

When they run into bugs in the library, they write issues and pull requests to the open-source repository. Their code ends up like this.

// The actions need to happen at a certain order.
// Otherwise the internal state of the boat object will corrupt.
// See this issue and discussion why an invalid state is possible using the transport library
// https://github.com/folklore-riddle/transport/issues/12
// Further documentation https://en.wikipedia.org/wiki/Wolf,_goat_and_cabbage_problem
function transferAnimals() {
// TODO There is a new version of the boat API in the making https://github.com/folklore-riddle/transport
// When the version is released, this function will be updated to use the new version.
boat.initialize(animals);
// `boat.load` is a bit awkward, but we have contributed to a PR open which simplifies it.
// Please see https://github.com/folklore-riddle/transport/pull/22
boat.load(GOAT_INDEX);
boat.moveToNextBank();
boat.unload();
boat.moveToNextBank();
boat.load(WOLF_INDEX);
boat.moveToNextBank();
boat.unload();
// NOTE! There is an issue in the boat state which causes the GOAT index be unloaded if we dont load the GOAT here.
// Issue https://github.com/folklore-riddle/transport/issues/53
boat.load(GOAT_INDEX);
boat.moveToNextBank()
boat.unload()
boat.load(GABBAGE_INDEX)
boat.moveToNextBank()
boat.unload()
boat.moveToNextBank();
boat.load(GOAT_INDEX)
boat.moveToNextBank()
boat.unload()
}
view raw solution.js hosted with ❤ by GitHub

The team understands the code could be better and could also isolate the unclean API in the codebase, but since they contributed to upstream, they decided to live with the clutter until it is released. They also write a unit test that fails if the library is updated, enforcing a rewrite.

Once you work with something confusing, clarify in your code (not just in the issue tracker) why it is illogical and why. Of course, in the ideal world, one creates abstractions that make it simpler but sometimes, it is just not possible or feasible.


They also could have just asked OpenAI!

Comments

Post a Comment

Popular posts from this blog

I'm not a passionate developer

A family friend of mine is an airlane pilot. A dream job for most, right? As a child, I certainly thought so. Now that I can have grown-up talks with him, I have discovered a more accurate description of his profession. He says that the truth about the job is that it is boring. To me, that is not that surprising. Airplanes are cool and all, but when you are in the middle of the Atlantic sitting next to the colleague you have been talking to past five years, how stimulating can that be? When he says the job is boring, it is not a bad kind of boring. It is a very specific boring. The "boring" you would want as a passenger. Uneventful.  Yet, he loves his job. According to him, an experienced pilot is most pleased when each and every tiny thing in the flight plan - goes according to plan. Passengers in the cabin of an expert pilot sit in the comfort of not even noticing who is flying. As someone employed in a field where being boring is not exactly in high demand, this sounds pro...
Post a Comment
Read more

Canyon Precede:ON 7

I bought or technically leased a Canyon Precede:ON 7 (2022) electric bike last fall. This post is about my experiences with it after riding for about 2000 km this winter. The season was a bit colder than usual, and we had more snow than in years, so I properly put the bike through its paces. I've been cycling for almost 20 years. I've never owned a car nor used public transport regularly. I pedal all distances below 30km in all seasons. Besides commuting, I've mountain biked and raced BMX, and I still actively ride my road bike during the spring and summer months. I've owned a handful of bikes and kept them until their frames failed. Buying new bikes or gear has not been a major part of my hobby, and frankly, I'm quite sceptical about the benefits of updating bikes or gear frequently. I've never owned an E-bike before, but I've rented one a couple of times. The bike arrived in a hilariously large box. I suppose there's no need to worry about damage durin...
Post a Comment
Read more

Emit structured Postgres data change events with wal2json

A common thing I see in an enterprise system is that when an end-user does some action, say add a user, the underlying web of subsystems adds the user to multiple databases in separate transactions. Each of these transactions may happen in varying order and, even worse, can fail, leaving the system in an inconsistent state. A better way could be to write the user data to some main database and then other subsystems like search indexes, pull/push the data to other interested parties, thus eliminating the need for multiple end-user originating boundary transactions. That's the theory part; how about a technical solution. The idea of this post came from the koodia pinnan alla podcast about event-driven systems and CDC . One of the discussion topics in the show is emitting events from Postgres transaction logs.  I built an utterly simple change emitter and reader using Postgres with the wal2json transaction decoding plugin and a custom go event parser. I'll stick to the boring ...
Post a Comment
Read more