Jul 21, 2024
Documenting Makefiles via a help message —
I’ve written in the past about using Makefiles for build automation and documentation. But sometimes I wish to provide help to users, that doesn’t require being a Makefiles expert to read!
Let’s explore how we can teach users our build system by turning the project’s Makefile (and awk) into a cheap documentation-as-code tool.
What it looks like make help Code Snippet 1: How to ask for help Figure 1: Result of asking for help…
Apr 1, 2024
My python toolbox —
The packaging workflow of Python has historically been a bit messy, starting with pip being just good enough, and virtualenvs being a great idea but a bit unwieldy. Installation was difficult, and tools like anaconda filled the gaps.
Lately, there’s been renaissance of package tooling in Python thanks to other languages innovating in the area, inspiring and pollinating the ecosystem, improving the comfort of development.
I want to present here the tools that I use to work with Python, usually latest iterations on well known concepts, to show that Python can be both fun to play with, and safe enough if we use modern tools.…
Mar 28, 2024
Reframing tickets as engineering records —
In the software world, tickets (as implemented in Jira, etc) often have a bad reputation, and I think it’s undeserved, once we reframe what, or who tickets are for.
In this article I want to revisit the purpose of tickets, usually “tickets for project management”, explore an alternative viewpoint of “tickets as engineering records”, and highlight how tickets should be useable as asynchronous alternative to (synchronous) communication.
Tickets as project management Under this fairly common viewpoint, tickets are a project manager’s tool, almost inflicted upon devs, likely in an attempt to punish them for their arcane powers over machine, who knows (I’m of course exaggerating on purpose).…
Feb 1, 2024
Embrace the Early Exit —
In programming, there are patterns everywhere: patterns of building code, patterns for organising components, even patterns for how to test things. A whole industry is looking for patterns to solve all their problems.
But amongst them all, there’s one pattern I whole-heartedly love, it’s the Early Exit. In this short and sweet post, I want to declare my undying love to the Early Exit, sharing my excitement.
From If+else to ladders and conditionals hell Functions routinely need to check some edge case isn’t hit, usually with more edge cases than actual routine happy-path code lines.…
Dec 15, 2023
Offline developer docs: Dash docsets via Zeal —
Since my earliest university days, I’ve spent a lot of time trying to get better at computers, immersing myself in the world of Linux, and generally improving my software development skills.
One of the aspects that was the most helpful to help me grow was attempting to replicate my normal dev workflow, but with less: Learn to operate on Linux not Windows, then learn to do dev via on the terminal instead of GUIs, and eventually learn to do the same but offline, without any network calls.…
Jun 30, 2023
My git worfklow —
Every now and then, at work, I find myself discussing git worfklows, commit messages, branching, releasing, versioning, changelogs etc. Since my opinion has remained fairly consistent for the past few years, I found myself repeating the same points a lot, so I wrote it down. This page is the resulting compilation of my opinions on the software development lifecycle (SDLC), without workplace-specific tangeants.
The article is broken down into ideas + recommendations, with recommendations in bold.…
Apr 5, 2023
Quick-start project templates via cookiecutter —
The most boring part of setting up a new code project is typing the boilerplate: it’s easy to forget bits, so we just copy the last project’s folder and “file the serial numbers off” on the project name.
Copy-pasta-driven project setup is not great though, as it’s too easy to forget replacing values in obscure files, or misunderstand why project is set up that way in the first place, leading to nasty surprises down the line.…
Oct 23, 2022
Presentation: Makefiles for build automation and documentation —
Last Friday, I performed a presentation to my colleagues about Makefiles, and I want to share it to the public.
Of note, this presentation is setting aside what people usually know of Makefiles (autoconf-generated blobs, opaque to any inspection because machine-created), and instead I introduce the concept of file transformation as a graph, then teach Makefiles basics (using SQL commands as an example). We then move on to my plea for simple Makefiles, and their potential for both documentation (explain what your codebase commands are, to the juniors), and as lightweight automation (avoid typing long boring commands).…
May 7, 2022
Literate wordle —
I’ve recently written a series of articles about Gherkin: its usage for requirements gathering, about its uses in BDD, and a lower-tech alternative to Cucumber, which I’m still experimenting with.
I wanted to showcase all of these ideas brought together, as well as show how comfy modern Python tooling can be. But more than writing code, I would need to explain my reasoning as we draft the program. So I picked up again a tool I always wanted to play with: Literate Programming.…
May 7, 2022
Reinventing IP Fragmentation —
Let’s explore how a file-format design exercise turned into reinventing the wheel, and let’s all appreciate how lucky we are that the protocols that the internet are built on have fantastic public documents called RFCs.
Designing a file format I was idly thinking about designing a good binary file format for a side project of mine called qrxfil. The project aims at QR-code-based file export: split a file in many pieces (based on content limit of QR codes) before reassembling it on the other side.…