Skip to content

Vendored a QR encoder — Reed‑Solomon over GF(256), fixed module layout, eight mask patterns — in 522 lines rather than take a third runtime dependency, and verified it by reading the finished matrix back with an independently written decoder.

Situation. The documents needed a QR code linking to the online version. Every available library does this, and taking one would have added a third runtime dependency to a project that had deliberately held itself to two — a template engine and a PDF renderer — on the argument that a document generator should still install years from now.

Task. Either accept the dependency or implement the format, and the implementation had to be verified as correct rather than merely producing something square and black.

Action. The encoder is 522 lines and implements the parts of the specification the use actually needs: byte‑mode encoding, Reed‑Solomon error correction over the Galois field of 256 elements with the generator polynomial built at the required degree, the fixed module layout with its finder patterns, timing patterns and alignment patterns, format and version information, and all eight data mask patterns evaluated against the specification’s four penalty rules so the lowest‑scoring mask is chosen rather than a fixed one. The verification is the part that made it defensible. Testing an encoder against its own logic proves nothing, so the finished module matrix is read back by a decoder written independently from the specification’s reading order, and the test asserts that the decoded string equals the input. That turns “it produces a plausible image” into “it produces a code that decodes to the right URL”, and it is checked on every run rather than once by eye with a phone.

Result. The runtime dependency count stayed at two, and the encoder is the only vendored component in the project. It should be said plainly that this is not a general‑purpose implementation — it supports the modes and versions the documents use and nothing else, and the honest justification is the dependency budget rather than any claim that the result is better than a mature library.