Introduction

Swift extensions are easy to add, but poor file naming quickly makes large projects hard to navigate. A good extension file name should reveal both the extended type and the added capability. The primary goal is discoverability for future maintainers.

Use Type+Capability.swift

A practical default convention is Type+Capability.swift.

Examples:

• 'String+Validation.swift'
• 'Date+Formatting.swift'
• 'UIView+Layout.swift'
• 'URLRequest+AuthHeaders.swift'

1// File: String+Validation.swift
2import Foundation
3
4extension String {
5    var isEmailLike: Bool {
6        contains("@") && contains(".")
7    }
8}

This naming style is predictable and works well with search and code navigation.

Keep One Responsibility Per Extension File

Avoid putting unrelated extension methods in one file. Large generic files such as Extensions.swift become dumping grounds and increase merge conflicts.

Better split by concern:

• 'URL+Routing.swift'
• 'URL+QueryItems.swift'

1// File: URL+QueryItems.swift
2import Foundation
3
4extension URL {
5    func appendingQueryItem(name: String, value: String) -> URL {
6        guard var components = URLComponents(url: self, resolvingAgainstBaseURL: false) else {
7            return self
8        }
9
10        var items = components.queryItems ?? []
11        items.append(URLQueryItem(name: name, value: value))
12        components.queryItems = items
13        return components.url ?? self
14    }
15}

Small focused files reduce review noise and improve ownership clarity.

Protocol Conformance Naming

When an extension mainly adds protocol conformance, name the file accordingly.

Examples:

• 'User+Codable.swift'
• 'Order+Equatable.swift'
• 'Invoice+CustomStringConvertible.swift'

1// File: User+Codable.swift
2import Foundation
3
4struct User {
5    let id: Int
6    let name: String
7}
8
9extension User: Codable {}

If conformance is central to the type identity, keeping it with the main type file can also be valid. Consistency across the codebase matters most.

Account for Module Context

In modular apps, the same type may be extended differently in separate domains. Include domain terms in the capability segment when helpful.

Examples:

• 'Date+BillingPeriods.swift'
• 'Date+AnalyticsBuckets.swift'

This prevents confusion and keeps search results relevant in large repositories.

Team Conventions and Enforcement

Naming conventions are only effective if documented and reviewed.

Suggested lightweight rules:

• Include extended type name.
• Include one capability or protocol role.
• Avoid vague names like Helpers or Utils.
• Keep unrelated concerns in separate files.

You can enforce this through code review templates or simple lint checks in CI.

Migrating Legacy Extension Sprawl

If the repository already has oversized extension files, refactor incrementally:

1. Define target naming convention.
2. Split one type at a time.
3. Keep behavior unchanged during moves.
4. Add tests before major regrouping.

Incremental cleanup is easier to review and less risky than one large rename-only pull request.

Pull Request Review Checklist

A short checklist keeps naming quality from drifting over time. Confirm the file name includes the extended type, confirms one clear capability, and matches the methods present in the file. Also verify that new extension files follow existing module conventions instead of introducing one-off naming patterns. Consistent review habits are more effective than large style documents nobody reads.

Common Pitfalls

• Using generic file names that hide both type and purpose.
• Grouping unrelated extension methods for convenience.
• Applying personal naming preferences without team consistency.
• Splitting protocol conformances inconsistently across modules.
• Performing large extension renames without tests and clear migration steps.

Summary

• Prefer Type+Capability.swift for clear extension discoverability.
• Keep each extension file focused on one coherent concern.
• Name protocol-conformance files explicitly when useful.
• Document conventions and apply them consistently in reviews.
• Refactor legacy extension files gradually with test coverage.