diff --git a/.github/workflows/pr-check-managed-files-hosted.yml b/.github/workflows/pr-check-managed-files-hosted.yml index d54ca33..11f0c91 100644 --- a/.github/workflows/pr-check-managed-files-hosted.yml +++ b/.github/workflows/pr-check-managed-files-hosted.yml @@ -80,6 +80,7 @@ on: - docs/standards/README.md - docs/standards/bulk-mutation.md - docs/standards/concise-prose.md + - docs/standards/configuration-switch-naming.md - docs/standards/design-for-change.md - docs/standards/deterministic-work-execution.md - docs/standards/documentation-and-citations.md diff --git a/docs/standards/README.md b/docs/standards/README.md index c957f67..77da4e3 100644 --- a/docs/standards/README.md +++ b/docs/standards/README.md @@ -12,6 +12,7 @@ there, not here. |---|---|---| | bulk-mutation | a command or sweep that creates, deletes, or changes many objects; background or unattended runs; work spanning several targets | bulk-mutation.md | | concise-prose | writing or reviewing any prose: docs, comments, commit messages, PR bodies, replies | concise-prose.md | +| configuration-switch-naming | naming or reading an environment variable, CI, organization or repository variable, or settings key that turns a behavior on or off | configuration-switch-naming.md | | design-for-change | designing or reviewing a module boundary, an extension point, configuration, dependency wiring, or a design pattern; any change whose reversal would edit many files | design-for-change.md | | deterministic-work-execution | counts, diffs, sorting, arithmetic, inventories; composing shell commands an agent runs | deterministic-work-execution.md | | documentation-and-citations | citing upstream docs; recording an external default or version; labeling the basis of a recommendation | documentation-and-citations.md | diff --git a/docs/standards/configuration-switch-naming.md b/docs/standards/configuration-switch-naming.md new file mode 100644 index 0000000..102d078 --- /dev/null +++ b/docs/standards/configuration-switch-naming.md @@ -0,0 +1,44 @@ +# Configuration switch naming + +A configuration switch is a value outside the code that turns a behavior on or +off: an environment variable, a CI, organization or repository variable, or a +settings key. Name it so that leaving it unset is always the normal, safe state. +[`naming.md`](https://github.com/melodic-software/standards/blob/main/standards/engineering/naming.md) +owns names in general; this file owns only on/off switches. + +## Rules + +- **A switch that turns off a default-on behavior is named `_DISABLED`.** + Unset or empty means the default: on. No caller needs a `|| 'true'` fallback, + and a missing variable never turns the behavior off by accident. Our + organization variables follow this: `CLAUDE_LANES_DISABLED`, + `CLAUDE_REVIEW_DISABLED`, `CLAUDE_SECURITY_REVIEW_DISABLED`, + `CLAUDE_API_KEYS_DISABLED`. +- **A switch that turns on a default-off behavior is named `_ENABLED`.** + Unset or empty means off. +- **Values are `true` and `false`.** Read the value as `true`, compared without + case; any other value, unset included, is false. New switches never take `0` + and `1`, `yes` and `no`, or presence alone. +- **Booleans inside code stay affirmative** (`isEnabled`, `canSeek`): a + property, parameter or field always holds a value, so it has no unset state + for a negative name to protect. + +## Why + +The negative name puts the default in absence. [NO_COLOR](https://no-color.org/) +uses the same shape: the variable, "when present and not an empty string +(regardless of its value), prevents the addition of ANSI color". It reads +presence, so `NO_COLOR=false` still turns color off; that is the reason for the +value rule above. + +Mixed value rules cause wrong settings: a tool that reads some switches by +presence and others as booleans lets `0` mean on for one and off for another. +Claude Code's +[environment variables page](https://code.claude.com/docs/en/env-vars) shows +the hazard; read it for the current behavior of each variable. One value rule +for every switch removes the guesswork. + +Code booleans follow the .NET +[Framework Design Guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/names-of-type-members): +"DO name Boolean properties with an affirmative phrase (`CanSeek` instead of +`CantSeek`)."