💾 Archived View for warmedal.se › ~bjorn › posts › breaking-apart-code.gmi captured on 2024-06-16 at 12:35:32. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Breaking Apart Code

I recently made a larger refactoring of one of my projects, and a part of that refactoring was to split a larger file into a few smaller ones. Any friend of order would at this point ask why I would do that. Does that make the code better?

No, the code didn't become better or more efficient. In fact one component became arguably more bloated (and I'm pondering ways to fix that). But for me the positives outweigh the negatives on this one, because structure matters when it comes to maintainability. And it matters outside of this specific project as well.

I don't know if this is a general and transferable rule or principle, but this at least stands true for me:

A project usually builds on or grows out of another, existing project.

There's a direct timeline to follow where my projects have gone through evolutionary stages or generations in the past few months.

I wrote a CLI tool for making gemini calls, originally in an effort to understand SSL and socket handling in python.
I used this tool for a cron job that compiles a report on the state of the AstroBotany garden four times a day.
I wrote Antenna, which makes gemini calls every now and then to fetch new content.
I wrote the Wobbly web-based gemini browser, powered by a CGI script that (you guessed it) makes gemini calls.

When I came to that fourth bullet I realised that this would be the third time I would implement gemini calls in python from scratch. It didn't make sense anymore. So I rebuilt gemcall, the CLI tool, into a python library and used that in Wobbly. Not only did it make the Wobbly code base smaller, but it also made it a lot more obvious what Wobbly is and what it isn't. The Wobbly backend's primary purpose isn't actually to fetch gemini content, but to serve it in a way that is suitable for rendering in a web browser.

So when returning to a previous project to refactor it, it made sense to rip out all the gemini call magic and replace it with gemcall. Because making gemini calls is not the purpose, but a means to an end.

That bullet list doesn't in any way end after four bullets, of course. When I dissected this project and split the code base into more parts it helps me crystallize what this particular project is about. What its core is. And the parts I've broken out that are particularly well designed may sometime in the future be completely disconnected from this project and made into libraries that will be reused in later projects.

I have a CLI tool that converts gemtext to HTML, but when I needed to do the same in Wobbly I wrote a general gemtext parser instead, and used that for a Wobbly-specific way of translating to HTML. Why? Because one of the projects on my back burner is another gemini browser, and a general parsing library will stop me from parsing gemtext a third time.

Divide and conquer. Use bricks to build modules, which you can later use to build houses.

Relevant Links

Yes, I'm talking about Antenna again.

And again.

Garden Gnome Society, my AstroBotany fan service.

Wobbly, the web-based gemini browser.

-- CC0 ew0k, 2021-08-21