Some lessons from a side project

2023-05-28 • 912 words • ~4 min read ⏲

Last year one evening my whole family was asleep unusually early. On contrast, I was not particularly tired, which is equally unusual. I used the time that I unexpectedly had at my disposal to write a tiny web app for managing my bookmarks.

Initially my goal for this article was to describe the app and its making on both a technical and non-technical level, but I got a bit lost in discussing and justifying technical minutiae, which aren't that essential. What follows is an attempt to describe the psychology of writing a simple, yet useful system in a very limited amount of time.

An itch to scratch

I regularly jump between multiple browsers on several physical and virtual machines, and I bookmark quite a lot. And if it weren't for the further, I'd be happy with the browser built-in bookmarks. I never really found a solution for keeping bookmarks in sync that suited my taste. Still, my requirements are simple. I just want a single place where I can reach all of my bookmarks, and a way to add a link with a single click.

Certainly, bookmarking-as-a-web-app has been tackled many times over. I could have taken the sane persons' approach and just subscribe to some SaaS, or I could have searched for some open source solution that to host for myself. But then again, I'm a programmer, and it seems this comes with a déformation professionelle that got the better of me. I like to call it inverse vandalism (when vandalism is destroying things just because one can, then inverse vandalism is making things because one can). Those who want to take a look at the code first can do that here.

A few foolish assumptions

Feeling the compulsion to open the IDE and start hacking is the one thing, but there is one very hard limitation: having a chunk of uninterrupted time with good attention span available. Most of that is sold to my employer already. So when I have a good timeslot, in order to get something into a working state, its complexity must be rigorously limited. To keep the program as small as possible and overcoming the the hardest limit of all, the available tiem, deciding what is out of scope is probably more important than programming the actual features. And define a certain class of problems out of existence is a remarkable productivity boost.

Many, if not all, of the assumptions I took are unthinkable in a commercial setting. Yet they turned out to be liberating in this little project. The most fundamental was, that I wanted to create a system, which is intended for me alone to use. This freed me from a whole lot of yak-shaving. Assuming a single user means I don't even need to explicitly model it out. It made it easy to estimate how much (or rather how little) memory my data will consume, and as a second order effect, suddenly the filesystem is justifiable as a good enough storage mechanism.

So what remains to have a most rudimentary bookmark manager? A mechanism to add a url, to delete it again and to render the collection of all links. All of which is accomplished by a single node.js based script which reads in a file of all bookmarks into memory and provides three endpoints. One to render all bookmarks in a single page, one to add another bookmark to the file and one to delete a single bookmark. The endpoint to add a new link is meant to be called via a bookmarklet.

Of course, a system based on those assumptions is tautologically not able to scale. But the alternatives would not have potentially scalable software vs. the scrappy single-user system. It was either something I could do in a single good session, or not creating something at all.

Lessons learned

Hillel Wayne dedicated an issue of his fantastic Computer Things newsletter to the question What can you code up in an hour?. He writes Fast programming is a distinct skill from software engineering. Software engineering principles don’t totally map over. - and this matches quite a bit with what I learned from writing this little script (and running it without major maintainance ever since).

Don't hesitate to rigorously limit scope. Make an art form out of cutting corners. Minimize the number of moving parts. YAGNI, really.

If the project is not an exercise for the sake of learning a new technology, use familiar tools. The standard library is your friend.

Most best practices are trade-offs, which, if a certain time/complexity threshold is not reached, might not pay off.

Data > API > UI. If I ever wanted to evolve what I have, the only thing I would definitively want to keep are the over 1000 bookmarks I've collected.

Learn to recognise chunks of good time as they come and grasp them firmly. You don't need anybodys permission to experience the joy that comes in creating something for yourself. Just keep in mind, when project time collides with in-person time with your most important people, that the tail end comes faster than you realize.