Coding Standards#
Standards for code written anywhere in the MSX ecosystem, in two tiers. The baseline encodes the Principles at the level of day-to-day code — how it is named, laid out, documented, tested, and secured — and applies in every language. The per-language standards add the idioms of one language or tool on top, and never contradict the baseline.
These standards are prescriptive, and they are the source of truth: the relevant linter or formatter is the enforcement mechanism, and its configuration is derived from the standard — never the other way around. Wherever a rule can be checked mechanically, a linter derived from the standard enforces it in CI.
Contents#
The baseline pages apply to all code and come first; the per-language standards build on them and follow.
| Page | Description |
|---|---|
| Naming | Names that reveal intent, consistently, in every language. |
| Code Layout | Structure, formatting, and file organization. |
| Functions | One responsibility, contracts in the signature, and validation at the boundary. |
| Error Handling | Fail fast, never swallow, and write messages that help the next person. |
| Documentation | Help that lives next to the code and explains the why. |
| Testing | The executable specification — test-first, locally runnable, deterministic. |
| Performance | Scale with the input, measure before optimizing, clarity first. |
| Security | Least privilege, secret hygiene, and the OWASP baseline. |
| GitHub Actions | Workflow authoring — SHA pinning, least-privilege permissions, OIDC, secrets handling, a PowerShell-first scripting default, script extraction, and diagnostic logging. |
| Markdown | GitHub Flavored Markdown authoring rules enforced by the shared markdownlint configuration. |
| PowerShell | Cross-platform PowerShell 7 — the conventions shared by every script, function, and class, with per-construct standards below. |
| Terraform | Stack layout, version pinning, state and secrets, and the fmt/validate/tflint toolchain. |
| TypeScript | ES modules, strict-mode typing, pinned dependencies, and the Prettier/ESLint/Vitest toolchain for Node tooling and VS Code extensions. |
Two tiers#
The baseline applies in every language — naming, code layout, functions, error handling, documentation, testing, performance, and security. Every repository inherits it.
The per-language standards capture the idioms of one language or tool: the conventions, the toolchain that enforces them, and the rationale where it is not obvious. A PowerShell module, a Terraform stack, a GitHub Actions workflow, and a Markdown document each have idioms of their own. A per-language standard always builds on the baseline and never contradicts it — where they overlap, the baseline rule applies and the per-language page adds the specifics.
The one rule above the rules#
Code is read far more often than it is written.
Every standard here serves that single fact. When a rule and readability disagree, readability wins — and the rule gets revisited. When in doubt, optimize for the next person (or agent) who has to understand the code cold.
How standards evolve#
Standards are evergreen, not frozen. When one stops serving us, we change it — in a pull request, against this repository, with the reasoning written down. A standard that cannot be justified is a standard that should be removed.