references/argument-labels.md
# Argument Labels
## Omit Labels Only When It Is Still Clear
- Omit all labels only when unlabeled arguments cannot be usefully distinguished.
Examples:
- `min(x, y)`
- `zip(a, b)`
## Value-Preserving Conversion Initializers
- Omit the first argument label for value-preserving conversions.
- The first argument should be the conversion source.
```swift
let value = Int64(someUInt32)
```
## Prepositional Phrase Rule
- If the first argument is part of a prepositional phrase, usually include the label beginning with the preposition.
```swift
x.removeBoxes(havingLength: 12)
```
Exception:
- When first arguments are parts of one abstraction, move the label boundary after the preposition.
```swift
a.moveTo(x: b, y: c)
a.fadeFrom(red: b, green: c, blue: d)
```
## Grammatical Phrase Rule
- If the first argument forms part of a grammatical phrase, omit its label and move leading words into the base name.
```swift
x.addSubview(y)
```
## Label Everything Else
- If the first argument is not part of a grammatical phrase, label it.
- Label all remaining arguments unless a specific rule justifies omission.
```swift
view.dismiss(animated: false)
words.split(maxSplits: 12)
students.sorted(isOrderedBefore: Student.namePrecedes)
```
references/fundamentals.md
# Fundamentals
## Core Priorities
- Clarity at the point of use is the most important design goal.
- Clarity is more important than brevity.
- Evaluate declarations in real call-site context, not in isolation.
## Documentation Is Part Of API Design
- Write a documentation comment for every declaration.
- If the API is hard to describe simply, redesign may be needed.
- Use Swift Markdown and recognized symbol markup.
## Summary Writing Rules
- Start with a summary that can stand on its own.
- Prefer a single sentence fragment ending in a period.
- Describe:
- Functions/methods: what they do and return.
- Subscripts: what they access.
- Initializers: what they create.
- Other declarations: what they are.
## Suggested Structure
```swift
/// Returns a "view" of `self` containing the same elements in
/// reverse order.
func reversed() -> ReverseCollection
```
```swift
/// Accesses the `index`th element.
subscript(index: Int) -> Element { get set }
```
```swift
/// Creates an instance containing `n` repetitions of `x`.
init(count n: Int, repeatedElement x: Element)
```
## Additional Comment Content
- Add extra paragraphs only when they improve comprehension.
- Use symbol markup bullets when relevant, such as:
- `Parameter` / `Parameters`
- `Returns`
- `Throws`
- `Note`
- `Warning`
- `SeeAlso`
## Practical Check
- Read a use-site snippet and confirm the intent is obvious without external explanation.
references/general-conventions.md
# General Conventions
## Document Computed Property Complexity
- If a computed property is not `O(1)`, document its complexity.
- Many readers assume property access is cheap unless told otherwise.
## Prefer Methods/Properties To Free Functions
Use free functions only when:
1. There is no obvious `self`.
2. The function is an unconstrained generic.
3. Function syntax is established domain notation.
## Follow Swift Casing
- Types/protocols: `UpperCamelCase`.
- Other declarations: `lowerCamelCase`.
- Acronyms and initialisms should be cased consistently with style conventions.
```swift
var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var radarDetector: RadarScanner
```
## Overloads
- Methods may share base names when meaning is the same or domains are distinct.
- Do not reuse a base name for semantically different operations.
- Avoid overloading on return type alone; type inference can make calls ambiguous.
## Review Heuristic
- Check that overload sets are readable, semantically coherent, and unambiguous at call sites.
references/parameters.md
# Parameters
## Choose Names For Documentation Quality
- Parameter names do not appear at most call sites, but they drive documentation clarity.
- Select names that read naturally in summaries and parameter descriptions.
```swift
/// Returns the elements of `self` that satisfy `predicate`.
func filter(_ predicate: (Element) -> Bool) -> [Element]
```
## Prefer Defaults For Common Cases
- Use default values when one value is commonly used.
- Defaults reduce noise in common call sites and improve readability.
```swift
lastName.compare(royalFamilyName)
```
## Prefer A Single API With Defaults Over Method Families
- Multiple overloads with mostly shared semantics increase cognitive load.
- One method with defaults is usually easier to learn and maintain.
## Place Defaulted Parameters Near The End
- Non-defaulted parameters typically carry core semantics.
- Keep the call pattern stable and predictable.
## `#fileID`, `#filePath`, `#file`
- Prefer `#fileID` for production APIs to save space and avoid exposing full paths.
- Use `#filePath` where full paths are intentionally useful (e.g., tests/tools).
- Use `#file` for Swift 5.2-and-earlier compatibility needs.
references/promote-clear-usage.md
# Promote Clear Usage
## Include Words Needed For Clarity
- Keep all words required to avoid ambiguity at the call site.
- Do not remove words that carry semantic distinction.
```swift
employees.remove(at: index) // clear position-based removal
employees.remove(index) // ambiguous
```
## Omit Needless Words
- Remove words that repeat type information and add no meaning.
- Prefer role-focused words over type-focused words.
```swift
allViews.remove(cancelButton) // preferred
allViews.removeElement(cancelButton) // redundant
```
## Name By Role, Not Type
- Variables, parameters, and associated types should describe role.
- Avoid reusing type names as identifiers when a role name is better.
```swift
var greeting = "Hello"
func restock(from supplier: WidgetFactory)
associatedtype ContentView: View
```
## Compensate For Weak Type Information
- Weakly typed values (`Any`, `NSObject`, primitives) often need extra role words.
- Add role nouns to disambiguate intent.
```swift
func addObserver(_ observer: NSObject, forKeyPath path: String)
```
## Review Heuristic
- Ask: "Can a reader infer semantics from call-site text alone?"
- If not, add the smallest amount of naming context needed.
references/special-instructions.md
# Special Instructions
## Tuple And Closure Naming
- Label tuple members in API signatures.
- Name closure parameters where they appear in the API.
- These names improve call-site readability and documentation usefulness.
```swift
mutating func ensureUniqueStorage(
minimumCapacity requestedCapacity: Int,
allocate: (_ byteCount: Int) -> UnsafePointer<Void>
) -> (reallocated: Bool, capacityChanged: Bool)
```
## Be Careful With Unconstrained Polymorphism
- `Any`, `AnyObject`, and unconstrained generics can make overload sets ambiguous.
- Semantic overload families still need explicit naming when weak typing collapses distinctions.
Ambiguous pattern:
```swift
values.append([2, 3, 4]) // element append or sequence append?
```
Preferred disambiguation:
```swift
append(_ newElement: Element)
append(contentsOf newElements: S)
```
## Practical Rule
- If overload meaning is not obvious at the call site for weakly typed values, rename APIs to make intent explicit.
references/strive-for-fluent-usage.md
# Strive For Fluent Usage
## Build Grammatical Call Sites
- Prefer names that form readable phrases at use sites.
- Fluency matters most for the base name and first arguments.
```swift
x.insert(y, at: z)
x.subviews(havingColor: color)
```
## Factory And Initializer Naming
- Start factory methods with `make`.
- Do not force the first argument into a phrase with the base name.
```swift
factory.makeWidget(gears: 42, spindles: 14)
let link = Link(to: destination)
```
## Name By Side Effects
- No side effects: noun/query style (`distance(to:)`, `isEmpty`).
- With side effects: imperative verb style (`sort()`, `append(_)`, `print(_)`).
## Mutating/Nonmutating Pairs
- If naturally a verb:
- Mutating: imperative (`sort`, `append`)
- Nonmutating: participle (`sorted`, `appending`/`stripping...`)
- If naturally a noun:
- Nonmutating noun (`union`)
- Mutating `form` prefix (`formUnion`)
## Protocol And Type Naming
- Protocols describing what something is should be nouns (`Collection`).
- Capability protocols should end in `able`, `ible`, or `ing` (`Equatable`, `ProgressReporting`).
- Types, properties, constants, and variables should read as nouns.
references/use-terminology-well.md
# Use Terminology Well
## Prefer Clarity Over Obscurity
- Avoid obscure terminology when common words preserve meaning.
- Use terms of art only when they provide necessary precision.
## Preserve Established Meanings
- If you use a term of art, keep its accepted meaning.
- Do not redefine terms in ways that surprise experts or mislead newcomers.
## Avoid Unnecessary Abbreviations
- Non-standard abbreviations become hidden terms of art.
- Use abbreviations only when widely established in domain practice.
## Embrace Precedent
- Follow established technical vocabulary in Swift and the broader domain.
- Choose culturally standard names when they improve interoperability of understanding.
Examples:
- Prefer `Array` over inventing a new simplified synonym.
- In math-heavy APIs, `sin(x)` is better than over-explaining the name.