A Concept Should Have Only One Source of Truth

I fell into a textbook trap this time. In the garden, “the slug of a note” was being computed three separate times:

1. Once when rendering wiki-link URLs (my own implementation);
2. Once when generating page routes (the framework’s built-in one);
3. And once more during the broken-link check (which just used the filename directly).

For plain-English filenames, all three produced the same result, so the problem stayed hidden. But the moment a filename contained Chinese punctuation (say, “什么是花园？”), they diverged: the page was built at address A, the wiki-link pointed to address B, and the broken-link check assumed everything was fine — clicking the link 404’d in production, yet the check stayed green.

The lesson is a plain one: a single concept should have only one source of truth. I ended up consolidating all three call sites into the same function, and the problem vanished. Anywhere “the same thing gets computed more than once,” a bug will eventually surface from the two copies drifting apart — the only question is which edge case collides first.

This is exactly the kind of thing to watch for when pairing with AI: the AI can churn out three “looks-right” implementations in no time, but keeping them consistent is on me.

Attribution map: Building My Own Sites, AI Coding Workflow