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.

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.

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 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

Popular posts from this blog

Bird is causing high CPU on my macOS

There is no lack of people complaining about MacOS Tahoe, mostly about rounded corners and inconsistent design decisions. I have not paid that much attentention to that, but there is one mac bug i have paid attention to. It hasn't been a visual or ux but rather few system processes pegging the CPU. trustd , alongside with ecosystemd and ecosystemanalyticsd all reported high CPU usage. I can't exactly recall when this started, it might have predated my Tahoe upgrade but anyway, the trio of processes all had high CPU usage. Sure, it may have been the virtual efficiency cores and whether it affeced battery life or slowed down other processes i don't know to be hon...

How my work has changed in the past few years

When I started at my current job 3ish years ago, we had nothing but a few PowerPoint slides and a Figma prototype. I recall talking with one of the founders, whom I had worked with some 10 years ago, and pointing out that the very next step after PowerPoint and Figma was still the same as it had always been: translating those slides and mockups into CRUDs, forms, and other basic building blocks. Sure, all the new fancy tools and frameworks (we had jQuery then) help, but I still had to tinker with very basic primitives like tables and forms. I could not just say, "here is a table, here is a form." Well, yes, technically I could, but I still needed to write a lot of code to make a working form or table. This was around the time of GPT-3, Copilot beta, and very early Cursor. I did attempt to use them, but they could only perform very basic tasks and were pretty much useless for frontend work. We, being one of the first-wave "ChatGPT wrapper" startups has naturally pus...

Building a OTel sink that follows GenAI semantic conventions

I've been working on an OTel sink recently. To be more specific, it concerns receiving telemetry data from LLM interactions. Fortunately, there is a spec for all of this called GenAI Semantic Conventions . That is what I based my work on, so I can make assumptions about key attributes to highlight in the sink's UI, which is actually a CLI in my case. I dogfooded my handrolled sink using Pydantic AI (my favorite LLM framework), and all good, it follows the spec well. Key attributes flow in as specified. Pydantic AI also includes some of its own attributes, but that is expected. However, pick something like Claude Code, (via anthropic agent sdk), the reality is a bit different. It does not follow the spec at all. It has its own custom attribute layout . Same direction, different flavor with LangChain. The Python source has zero opentelemetry imports anywhere. None. The ls_* namespace ( ls_provider , ls_model_name , ls_temperature ) is its own thing, with LangSmith as the on...