Coding Style Guide for apple/container: Swift Format Configuration

The apple/container repository defines its Swift coding style through a declarative JSON configuration in .swift-format that enforces 4-space indentation, 180-character line limits, and strict safety rules against force-unwrapping, all automated via make format and make check commands.

The apple/container project follows a machine-enforceable coding style guide rather than a traditional prose document. The repository uses the Swift Format tool with a dedicated configuration file to ensure consistent formatting across all Swift source files. Contributors adhere to these standards through automated pre-commit hooks and CI validation that reference the .swift-format file at the repository root.

Swift Format Configuration Structure

The canonical style guide lives in the .swift-format file at the repository root. This JSON configuration declares formatting rules that the Swift Format tool applies to the entire codebase, replacing manual style enforcement with automated correction.

Indentation and Line Length Rules

The configuration enforces strict whitespace standards to maintain readability across the codebase:

• Indentation: 4 spaces per indent level (configured on line 6)
• Line length: Maximum 180 characters per line (line 14)
• Blank lines: At most one consecutive blank line permitted (maximumBlankLines: 1, line 15)

Naming and Syntax Conventions

Identifier casing and punctuation follow deterministic rules:

• Lower camel case: AlwaysUseLowerCamelCase: true (line 26) requires identifiers follow standard Swift naming
• Semicolons: DoNotUseSemicolons: true (line 29) prohibits semicolon usage
• Trailing commas: multiElementCollectionTrailingCommas: true (line 16) mandates trailing commas in multi-element collections

Safety and Code Quality Rules

The style guide emphasizes defensive coding practices through strict prohibitions:

• Force unwrap: NeverForceUnwrap: true (line 35) forbids forced unwrapping of optionals
• Force try: NeverUseForceTry: true (line 36) prohibits try! expressions
• Implicitly unwrapped optionals: NeverUseImplicitlyUnwrappedOptionals: true (line 37) bans Type! declarations

Import Organization and Documentation Standards

Beyond formatting, the style guide enforces structural organization and documentation quality.

Ordered imports: OrderedImports: true (line 52) requires alphabetical ordering of import statements.

Documentation comments: UseTripleSlashForDocumentationComments: true (line 61) mandates that documentation use /// syntax and contain valid markup.

Early exits: UseEarlyExits: true (line 56) prefers guard statements with early returns over deeply nested if blocks.

Automated Enforcement and CI Integration

The repository enforces these rules through automation defined in the Makefile and scripts/pre-commit.fmt.

Make Targets

The Makefile provides two primary commands for style management:

• make format – Runs swift format with the .swift-format configuration to automatically rewrite files in place
• make check – Validates formatting without modifying files, returning non-zero exit codes if violations exist

Pre-Commit Hooks

The scripts/pre-commit.fmt script executes make check before allowing commits. If Swift Format detects any violations, the script aborts the commit and requires the contributor to run make format to auto-correct the issues.

Migration and Relaxation Configuration

The repository includes a .swift-format-nolint file that provides relaxed rules during codebase modernization. While this configuration exists for transitional periods, the CI pipeline strictly uses the canonical .swift-format rules, ensuring all merged code meets the production style standards.

Conformant Code Examples

The following Swift snippets demonstrate compliance with the apple/container style guide:

// ✅ Correct: lower-camel-case, no semicolon, no forced unwrap
func fetchData(for url: URL) async throws -> Data {
    guard let (data, _) = try? await URLSession.shared.data(from: url) else {
        throw MyError.unableToFetch
    }
    return data
}

// ✅ Correct: trailing commas in multi-element collections
let supportedPlatforms = [
    "macOS",
    "iOS",
    "watchOS",
    "tvOS",
]

// ✅ Correct: triple-slash documentation comments
/// Returns a formatted string for the given amount.
/// - Parameter amount: The monetary amount in cents.
/// - Returns: A locale-aware string representation.
func formattedAmount(_ amount: Int) -> String {
    // implementation …
}

To automatically apply these standards to your changes:

make format

Summary

• The apple/container coding style guide is defined declaratively in the .swift-format JSON configuration rather than prose documentation.
• Key rules include 4-space indentation, 180-character line limits, mandatory lowerCamelCase, and prohibition of semicolons, force unwraps, and force try statements.
• The scripts/pre-commit.fmt hook and make check command enforce these rules in CI, blocking commits with style violations.
• Contributors use make format to automatically rewrite code according to the canonical configuration before submission.
• A transitional .swift-format-nolint configuration exists for migration periods but is not used in production CI.

Frequently Asked Questions

What tool enforces the coding style guide for apple/container?

The Swift Format tool enforces the style guide using the .swift-format configuration file located at the repository root. The tool runs automatically through make check in CI and the scripts/pre-commit.fmt pre-commit hook.

How do I fix formatting violations before committing?

Run make format from the repository root. This command invokes Swift Format with the .swift-format configuration and automatically rewrites files to comply with the style rules. You can then stage the changes and commit.

What is the maximum line length allowed in apple/container Swift code?

The style guide permits 180 characters per line as defined in .swift-format line 14. Lines exceeding this limit will cause make check to fail and require reformatting.

Are force unwraps allowed in the apple/container codebase?

No. The configuration explicitly sets NeverForceUnwrap: true (line 35), NeverUseForceTry: true (line 36), and NeverUseImplicitlyUnwrappedOptionals: true (line 37). Any forced unwrapping syntax will be rejected by the automated checks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}