Identify what varies and why
List settings that differ between development, testing, and production. Explain the purpose, expected format, and consequences of an invalid value. Separate ordinary configuration from secrets that require protected storage and access.
Avoid settings whose names only make sense to the original developer. A value controlling how long a background task waits should state its unit and scope. Document whether changing it requires a restart or takes effect immediately.
Validate before accepting work
Check required values at startup or at an appropriate configuration boundary. A clear failure before serving requests can be easier to diagnose than a missing setting that appears only when one rare workflow runs.
Choose defaults deliberately. A convenient development default may be inappropriate in production, especially if it redirects work to an unintended external service. Make the active environment recognizable through safe operational metadata without exposing secret values.
Track changes like changes
Record who changes production configuration and why. Include configuration differences in release investigation so the team does not assume every behavioral change came from source code.
Provide a documented process for obtaining secrets and rotating them. Operators should not need to copy values from a colleague’s shell history or commit sensitive files to make the application run.
Test a fresh environment using the documentation. Missing variables and implicit local state become visible when the setup is repeated from scratch. A well-defined configuration contract makes the application easier to deploy, hand over, and recover without depending on the machine where it was first built.
A practical example.
A service might behave differently because of a feature setting, an external endpoint, or a missing credential. Document which settings are required, their meaning, and how each environment supplies them. Sensible defaults should not silently point a test environment at production data.
Validate important configuration during startup or deployment so a mistake fails clearly before users encounter it. Keep secrets out of source files and diagnostic output, and use the organization’s established secret-handling mechanism. Record changes with enough context to explain an incident later without storing sensitive values in the history. Test a missing or invalid setting deliberately: an actionable failure message can save more time than a long list of undocumented environment variables.
Put it into practice.
- Define required settings, valid values, and environment-specific boundaries.
- Validate consequential mistakes early and keep secrets out of logs.
- Track configuration changes alongside releases so behavior remains explainable.