one-pattern-one-way

One Problem, One Pattern, One Way

For each category of problem in a codebase, there is one pattern. One. Not "usually" one. Not "preferably" one. Not "one, except when it is more convenient to do something else." ONE.

Configuration loading? One way. Error handling? One way. Data validation? One way. HTTP requests? One way. Logging? One way. String constants? One way. The moment a second approach appears, you have two problems: the original problem and the problem of not knowing which solution to use. By the third approach, the codebase is a museum of abandoned conventions.

This is the most violated principle in software engineering. Not because developers do not understand it, but because every individual shortcut feels harmless. "It is just one place." "This module is different." "I will refactor it later." None of these excuses survive contact with a team.

The Categories

Every codebase faces the same categories of cross-cutting problems. For each one, pick a pattern and enforce it everywhere. The specific pattern matters less than the fact that there is exactly one.

Configuration

One settings pattern. Everywhere.

Python: Pydantic BaseSettings with .env file loading. TypeScript: Zod schema validating process.env. Go: Struct with envconfig tags.

Pick one. If the project uses Pydantic BaseSettings, then every module that needs a config value gets it from that settings object. No os.getenv() calls scattered in business logic. No dotenv.load() in random files. No config.yaml alongside the .env. One source of truth, one loading mechanism, one validation step.

GOOD:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    redis_url: str
    stripe_api_key: str
    max_retry_attempts: int = 3

    model_config = {"env_file": ".env"}

settings = Settings()

BAD -- three config patterns in one project:

# settings.py -- Pydantic (pattern 1)
class Settings(BaseSettings):
    database_url: str

# worker.py -- raw os.getenv (pattern 2)
REDIS_URL = os.getenv("REDIS_URL", "redis://localhost")

# billing.py -- dotenv + os.environ (pattern 3)
load_dotenv()
STRIPE_KEY = os.environ["STRIPE_API_KEY"]