Api-Design on PHP Boy Scout

Two API decisions that quietly contradict each other

Thu, 23 Apr 2026 00:00:00 +0000

Two design decisions on one enum, each sensible on its own, that would have quietly fought each other if I’d let them. I didn’t, but only because the second one is easy to get wrong and the compiler wouldn’t have said a word either way.

Decision one: promise the list can grow

#[non_exhaustive] on the Feature enum. It tells downstream code it can’t match the enum exhaustively, so it has to keep a wildcard arm, which in turn means adding a variant later is a non-breaking, minor-version change. Nobody’s match stops compiling just because the enum grew. The doc comment says exactly that: it “keeps variant additions a minor-version change for downstream matchers.”

Decision two: hand out the whole list

A convenience all() returning every variant, because iterating over the lot is something you genuinely want to do. The tempting signature is a fixed-size array, [Feature; 11]: you know precisely how many there are, so why not put it in the type?

Why those two can’t both be true

The catch is a quirk of Rust that often trips up people arriving from other languages: the length of a fixed-size array is part of its type. [Feature; 11], an array of exactly eleven features, and [Feature; 12], exactly twelve, are not one type holding a different number of items the way they might be elsewhere. They are two genuinely different, incompatible types, about as interchangeable as i32 and i64.

So the moment you add a twelfth variant, a fixed-size all() forces an unhappy choice, and both options are bad. Bump the array to [Feature; 12] and you break every caller who wrote the old length down. Leave it at 11 and the new variant is silently dropped, leaving you a function called all that doesn’t return all of them. Either way the #[non_exhaustive] promise (adding a variant breaks nobody) is quietly cancelled by a return type that welded today’s count into the public API.

So `all()` returns a slice

Which is exactly what it does, and the doc comment spells out why, in crates/rtb-app/src/features.rs:

#[non_exhaustive]
pub enum Feature {
 Init, Version, Update, Docs, Mcp, Doctor,
 Ai, Telemetry, Config, Changelog, Credentials,
}

pub const fn all() -> &'static [Self] {
 &[Self::Init, Self::Version, Self::Update, /* ...the rest... */]
}

A slice length is a value, not part of the type. Add a variant, the slice gets one longer, and not a single downstream signature changes. The promise holds.

The thing to watch for

#[non_exhaustive] is a promise about the future. A fixed-size array is a fact about the present. You can’t keep both at once, and nothing will warn you that you’ve contradicted yourself, because each decision is individually fine. The trap is always the second API surface that quietly re-bakes the flexibility the first one promised. When you mark a type “free to grow,” go and check that nothing in its public interface has secretly written down how big it is today.

One variadic, and I'd already spent it

Thu, 26 Mar 2026 00:00:00 +0000

I had a constructor I was rather pleased with. Hand go-tool-base’s root command its props and as many sub-commands as you like, and off it goes. Then I needed to thread some config file paths through it, reached for the obvious “just add a parameter,” and discovered I’d already spent my one variadic with no second one going spare.

The ergonomics I’d happily bought

NewCmdRoot ends in subcommands ...*cobra.Command. That trailing ... is a small luxury: callers write NewCmdRoot(props, build, deploy, status) and never have to think about slices. Variadics are lovely for exactly this, the “and as many of these as you fancy” argument.

The parameter I couldn’t add

Then config arrived, and the root command needed to know about some extra configuration file paths. The instinct is to add a parameter. The instinct is wrong, because there’s nowhere legal to put it.

You can’t write NewCmdRoot(props, configPaths ...string, subcommands ...*cobra.Command). Go allows a function exactly one variadic, and it must be the final parameter. Two variadics results in a compile error before you’ve finished the line (assuming your IDE does compile time checks for you), and fairly so: at the call site, how would Go ever know where the strings stopped and the commands began? So the variadic I’d spent on sub-commands was spent. There wasn’t another to hand.

The choices, and the one I took

You can demote the variadic. Make it subcommands []*cobra.Command and you’re free to add configPaths []string next to it. Correct, and it breaks every existing call: NewCmdRoot(props, build, deploy) becomes NewCmdRoot(props, []string{}, []*cobra.Command{build, deploy}). Uglier at every site, to solve a problem only some callers have.

You can reach for functional options, and for plenty of go-tool-base’s constructors that is exactly what happened. But the root builder is the one everybody calls first, with the simplest signature in the codebase, and I didn’t want the common case lugging option machinery around for the sake of the rare one.

What I actually did was add a second door. From pkg/cmd/root/root.go:

// NewCmdRoot creates the root command with Props wiring and optional subcommands.
func NewCmdRoot(props *p.Props, subcommands ...*cobra.Command) *cobra.Command {
	return NewCmdRootWithConfig(props, []string{}, subcommands...)
}

func NewCmdRootWithConfig(props *p.Props, configPaths []string, subcommands ...*cobra.Command) *cobra.Command {
	// ...
}

The new argument goes in as a plain []string, sat before the variadic, which is perfectly legal: one variadic, still last. Callers who care about config use NewCmdRootWithConfig explicitly, and NewCmdRoot becomes a one-line wrapper that delegates with an empty slice, so every existing caller compiles untouched and none the wiser. Two doors into the same room, granted, but the original door is exactly where everyone left it.

What it comes down to

A trailing variadic is a slot you fill once. It buys gorgeous ergonomics for the “as many as you like” argument, and in exchange it quietly forecloses on ever appending another parameter, because the next one has nowhere to stand. Once it’s spent, new arguments come in as ordinary parameters before the variadic, and the kind thing to do for your callers is to put that behind a second constructor and let the original keep delegating.

So spend the variadic deliberately. Give it to the argument that genuinely wants to be a loose list, not the first one that happens to be plural, because you don’t get a second.