akj.io

Any sufficiently advanced configuration contains a worse version of the programming language it was trying to avoid

Published
Reading
5 min

I've been advocating for just using a programming language for things that usually seem smart as a templating/config language. For fun I've been telling people "This is what I call Allan's Law" and something like "Yeah sure it might already exist, but having a programming law would be pretty cool!"

If you have been doing any kind of programming, you've most likely seen this pattern in build pipelines, but it's really in a lot of software, especially enterprise software.

Any sufficiently advanced configuration format will eventually contain a worse version of the programming language it was trying to avoid.

YAML & JSON come to mind personally, I've seen entire programming languages or almost implemented in these. A conditional, an expression, a cute little loop here and that also needs some string interpolation. Error handling... well maybe?

Before you know it, you have some pretty awesome stuff... but the problem is, it should just have been in the programming language. It's often a lot of lines, and you're lucky if a text editor can even highlight it.

Testing it? Well for pipelines mostly you have to push it and run it on the server. Not really something that feels good in any way.

Visual... erm, code example

Say you need to build, test, and deploy three services, but only the ones that actually changed. Here's an Azure DevOps pipeline doing that:

yaml
trigger:
  branches:
    include: [main]
 
parameters:
  - name: services
    type: object
    default: [api, web, worker]
 
stages:
  - ${{ each service in parameters.services }}:
    - stage: build_${{ service }}
      condition: |
        or(
          eq(variables['Build.Reason'], 'Manual'),
          contains(
            stageDependencies.detect.changes.outputs['filter.services'],
            '${{ service }}'
          )
        )
      jobs:
        - job: build
          pool:
            vmImage: 'ubuntu-latest'
          steps:
            - task: UseNode@1
              inputs:
                version: '22.x'
            - script: npm ci --prefix services/${{ service }}
            - script: npm test --prefix services/${{ service }}
            - ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}:
              - script: |
                  echo "Deploying ${{ service }}..."
                  npm run deploy --prefix services/${{ service }}

There's a compile-time loop (${{ each }}), runtime conditionals (condition: or(eq(...), contains(...))), template expressions (${{ if eq() }}), string interpolation, stage dependencies, and parameter types. That's two different expression languages in the same file, one evaluated at compile time and one at runtime. To test any of this logic you push a commit and wait for an agent.

Now imagine if Azure Pipelines had a TypeScript SDK instead:

ts
import { Pipeline, Stage, NodeTool } from "@azure/pipelines-sdk";
import { getChangedServices } from "./git-utils";
 
type ServiceName = "api" | "web" | "worker";
 
const services: ServiceName[] = ["api", "web", "worker"];
 
const pipeline = new Pipeline({
  trigger: { branches: ["main"] },
});
 
for (const service of services) {
  pipeline.addStage(
    new Stage(`build_${service}`, {
      pool: "ubuntu-latest",
      condition: (ctx) =>
        ctx.isManual || getChangedServices(ctx.changedFiles).includes(service),
      steps: [
        new NodeTool("22.x"),
        (ctx) => ctx.exec(`npm ci --prefix services/${service}`),
        (ctx) => ctx.exec(`npm test --prefix services/${service}`),
        ...(pipeline.sourceBranch === "refs/heads/main"
          ? [(ctx) => ctx.exec(`npm run deploy --prefix services/${service}`)]
          : []),
      ],
    })
  );
}
 
export default pipeline;

Same behavior. A for loop, an if, typed context objects. You can read it top to bottom and know what it does. Your editor gives you autocomplete, go-to-definition, and red squiggles when you mess up. This SDK doesn't exist, but Pulumi and CDK proved the pattern works for infrastructure. No reason CI/CD couldn't work the same way. So your company's internal random configuration, maybe that could also just be an SDK?

Testable

The TypeScript version is just code. You can write a test for the filtering logic with whatever you already use:

ts
import { describe, it, expect } from "vitest";
import { getChangedServices } from "./git-utils";
 
describe("getChangedServices", () => {
  it("detects api changes", () => {
    const files = ["services/api/src/index.ts", "README.md"];
    expect(getChangedServices(files)).toEqual(["api"]);
  });
 
  it("skips unchanged services", () => {
    const files = ["docs/setup.md"];
    expect(getChangedServices(files)).toEqual([]);
  });
});

The YAML version? You push, wait, read logs from an agent you can't SSH into, and wonder why contains(stageDependencies.detect.changes.outputs['filter.services'], 'api') evaluated to false this time.

Local?

It's not a given that it'll just be local first, but oh damn if you have something like CI/CD, being able to test it on a local machine is just gold. It being an SDK does not solve this, but it makes it a lot more likely in my opinion and experience.

Just keep logic out of the config

Having a schema is fine, but the moment you're writing conditionals or loops to produce an artifact for that schema, just use code. If the consumer needs YAML, your code can emit it.

So is it really my law?

Greenspun's Tenth Rule (~1993) says any sufficiently complicated C or Fortran program contains an ad-hoc, informally-specified, bug-ridden, slow implementation of half of Common Lisp. The Inner-Platform Effect is about systems so configurable they become worse copies of their host platform.

Matt Rickard wrote in 2022 that "every sufficiently advanced configuration language is wrong."

But for now I'll just call this my law, it's my website after all and once it's indexed and on the Wayback Machine who really knows the truth.