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
Post a Comment