Practices

This guide covers language-neutral code organization, design patterns, and architectural principles. For formatting and visual presentation guidance, see the code style guide.

General Principles

Documentation Standards

Command Examples

  • Use long option names, whenever possible, in command line examples. Readers, who are unfamiliar with a command, should not have to look up the meanings of single-character option names.

    ❌ Avoid:

    git log -n 5 --oneline
docker run -d -p 8080:80 -v /data:/app/data nginx

    ✅ Prefer:

    git log --max-count=5 --oneline
docker run --detach --publish 8080:80 --volume /data:/app/data nginx

  • Write for readers who may be unfamiliar with the tools being demonstrated. Provide context and explanation for complex command sequences.

Quality Assurance

  • Install project Git hooks as described in the environment guide to reduce turnaround from avoidable validation failures.

  • Run the validation workflow documented in the validation guide before opening pull requests.

  • Consider maintaining or improving code coverage when practical. Even if code coverage is already high, continue adding tests for unaddressed behavioral paths.

Architectural Principles

  • Robustness Principle (Postel’s Law): Be conservative in what you emit and liberal in what you accept.

  • Immutability First: Prefer immutable structures when internal mutability is not required.

  • Dependency Injection: Prefer explicit dependencies with sensible defaults over hidden globals.

  • Exception Chaining: Never silently swallow exceptions; chain or handle them explicitly with context.

Language And Workflow Overlays

Use language-specific practice guides when available:

Use workflow overlays only when they match your language/toolchain:

Use the language-neutral core guides alongside language-specific overlays: environment guide, validation guide, testing guide, and release guide.