@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/swift-api-design-guidelines/SKILL.md

@@ -1,451 +1,326 @@
 ---
 name: swift-api-design-guidelines
-description: "Swift API Design Guidelines: clarity at the point of use, naming for readability over brevity, argument labels and prepositional phrases, method vs property choice, mutating/nonmutating pairs, protocol naming, generic parameter names, and documentation comment conventions. Use when naming a type, method or parameter, deciding between a method and a property, writing doc comments, or reviewing an API surface for consistency with the standard library."
+description: "Swift API Design Guidelines: call-site clarity over brevity, argument labels and prepositions, method versus property, side-effect naming, mutating and nonmutating pairs, make factories, protocol and generic parameter names, casing, doc comments, complexity notes. Use when naming types, methods, properties or parameters, writing doc comments or reviewing an API for standard-library consistency. Not for language features, concurrency or lint config."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # Swift API Design Guidelines
 
-Apply the Swift API Design Guidelines when naming types, methods, properties, parameters, and argument labels. Targets Swift 6.3. For language features and syntax, see `swift-language`. For concurrency patterns, see `swift-concurrency`. For mixed requests, answer the API naming portion briefly, then route Swift type-system details to `swift-language` and lint configuration to `swiftlint` instead of implementing those sibling domains here.
-
-## Contents
-
-- [Argument Label Rules](#argument-label-rules)
-- [Side-Effect Naming](#side-effect-naming)
-- [Mutating and Nonmutating Pairs](#mutating-and-nonmutating-pairs)
-- [Documentation Comments](#documentation-comments)
-- [Clarity and Naming](#clarity-and-naming)
-- [Fluent Usage and Protocols](#fluent-usage-and-protocols)
-- [General Conventions](#general-conventions)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Argument Label Rules
-
-Argument labels determine how a call site reads. Apply these rules in order.
-
-### When to omit the first argument label
-
-**Grammatical phrase rule.** When the first argument forms a grammatical phrase with the base name, omit the label. Move any leading words from what would be the label into the base name instead.
-
-```swift
-// GOOD  -  reads as "add subview y"
-view.addSubview(y)
-
-// BAD  -  redundant label breaks the phrase
-view.add(subview: y)
-```
-
-**Value-preserving type conversions.** When an initializer performs a value-preserving (widening) conversion, omit the first argument label.
-
-```swift
-// GOOD  -  widening conversion, no label
-let value = Int64(someUInt32)
-let str = String(someCharacter)
-
-// Narrowing or lossy conversions keep a label
-let approx = Int64(truncating: someDecimal)
-let str = String(describing: someObject)
-```
-
-**Indistinguishable arguments.** When all arguments cannot be usefully distinguished, omit all labels.
-
-```swift
-// GOOD  -  arguments are peers
-let smaller = min(x, y)
-zip(sequence1, sequence2)
-```
-
-### When to use a prepositional label
-
-**Prepositional phrase rule.** When the first argument completes a prepositional phrase with the base name, label it with the preposition.
-
-```swift
-// GOOD  -  "remove boxes having length 12"
-x.removeBoxes(havingLength: 12)
-
-// GOOD  -  "fade from red"
-view.fade(from: red)
-
-// GOOD  -  "relative path from root"
-path.relativePath(from: root)
-```
-
-**Exception  -  abstraction boundary.** When the first two arguments represent parts of a single abstraction, fold the preposition into the base name so each component gets its own label.
-
-```swift
-// GOOD  -  x and y are parts of a single abstraction (a point)
-a.moveTo(x: b, y: c)
-
-// BAD  -  preposition attaches to first arg, leaving y unlabeled
-a.move(toX: b, y: c)
-```
-
-### Default: label everything else
-
-When no special rule above applies, label the argument.
-
-```swift
-// GOOD
-array.split(maxSplits: 2)
-button.setTitle("OK", for: .normal)
-controller.dismiss(animated: true)
-array.sorted(by: >)
-```
-
-### Argument label decision table
+Use this when choosing names for types, methods, properties, parameters and
+argument labels, and when writing the doc comments that go with them. Baseline:
+Swift 6.3.
+
+Out of scope, with where it goes instead:
+
+- Language features and syntax, such as `some` versus `any`: `swift-language`.
+- Concurrency: `swift-concurrency`.
+- Lint rules and configuration: `swiftlint`.
+
+When a request mixes these, answer the naming part briefly, then point to the
+sibling skill for the rest. Do not start implementing the sibling's domain.
+
+## Argument labels
+
+Decide the first argument's label by testing these in order; the first rule
+that applies wins.
+
+1. **Grammatical phrase.** If the first argument reads as part of a phrase that
+   starts in the base name, drop its label and move any leading words into the
+   base name: `addSubview(y)`, not `add(subview: y)`.
+2. **Conversion initializer.** A value-preserving (widening) conversion takes
+   no first label: `Int64(someUInt32)`, `String(someCharacter)`. A narrowing
+   or lossy one keeps a label that says so: `Int64(truncating:)`,
+   `String(describing:)`.
+3. **Indistinguishable peers.** When the arguments cannot usefully be told
+   apart, label none of them: `min(x, y)`, `zip(names, scores)`.
+4. **Prepositional phrase.** When the base name ends in a preposition that the
+   first argument finishes, the preposition becomes the label: `removeBoxes(havingLength: 12)`,
+   `fade(from: red)`, `relativePath(from: root)`.
+5. **One abstraction, several arguments.** If the first two arguments are parts
+   of a single idea, keep the preposition in the base name so each part gets
+   its own label: `moveTo(x: b, y: c)`, not `move(toX: b, y: c)`.
+6. **Otherwise, label it:** `split(maxSplits: 2)`, `setTitle("OK", for: .normal)`,
+   `dismiss(animated: true)`, `sorted(by: >)`.
 
 | Situation | Rule | Example |
-|-----------|------|---------|
-| First arg completes grammatical phrase | Omit label, merge words into base name | `addSubview(y)` |
-| Value-preserving init conversion | Omit first label | `Int64(someUInt32)` |
-| Arguments are indistinguishable peers | Omit all labels | `min(x, y)` |
-| First arg completes prepositional phrase | Label with preposition | `fade(from: red)` |
-| First two args form a single abstraction | Fold preposition into base name | `moveTo(x: b, y: c)` |
-| Everything else | Label it | `split(maxSplits: 2)` |
-
-For extended examples and edge cases, see [references/argument-labels-and-parameters.md](references/argument-labels-and-parameters.md).
-
-## Side-Effect Naming
+|---|---|---|
+| Reads as a grammatical phrase | no label; merge words into the base name | `addSubview(y)` |
+| Value-preserving init | no first label | `Int64(someUInt32)` |
+| Peers | no labels | `min(x, y)` |
+| Prepositional phrase | preposition is the label | `fade(from: red)` |
+| Two args, one abstraction | preposition in the base name | `cellAt(row:column:)` |
+| Anything else | label | `split(maxSplits: 2)` |
 
-Name functions and methods by their side effects.
+Edge cases, conversion kinds, parameter names and default arguments:
+[the argument labels reference](references/argument-labels-and-parameters.md).
 
-### Functions with side effects  -  imperative verbs
+## Method or property
 
-When a function mutates state, name it as an imperative verb phrase.
+A property answers a question about the receiver. Make it a property when it
+takes no arguments, has no side effects and cannot fail; callers will assume
+it is cheap, so if it is not O(1), document the cost. Make it a method when it
+needs input, changes state, can throw or suspend, or does work heavy enough
+that a property would mislead.
 
 ```swift
-// Mutates  -  imperative verb
-array.sort()
-array.append(newElement)
-list.remove(at: index)
-timer.invalidate()
-```
-
-### Functions without side effects  -  nouns or adjective phrases
-
-When a function returns a result without mutating anything, name it as a noun phrase, adjective phrase, or read as a description of what it returns.
-
-```swift
-// Pure  -  noun/description
-let d = point.distance(to: origin)
-let area = rect.intersection(other)
-let line = text.trimmingCharacters(in: .whitespaces)
-```
-
-### Boolean properties and methods
-
-Boolean properties and methods read as assertions about the receiver.
-
-```swift
-// GOOD  -  reads as "line is empty"
-line.isEmpty
-set.contains(element)
-url.isFileURL
-
-// BAD  -  not an assertion
-line.empty       // verb? adjective?
-set.includes     // incomplete phrase
+protocol TrackList {
+    var trackCount: Int { get }                   // a fact about the receiver
+    var isEmpty: Bool { get }
+    func tracks(by artist: Artist) -> [Track]     // needs input
+    mutating func shuffle()                       // changes state
+    func loadArtwork() async throws -> Image      // real work that can fail
+}
 ```
 
-For more examples, see [references/side-effects-and-mutating-pairs.md](references/side-effects-and-mutating-pairs.md).
-
-## Mutating and Nonmutating Pairs
+More in [the naming reference](references/naming-and-clarity.md).
 
-When an operation has both mutating and nonmutating variants, name them as a pair.
+## Naming by side effect
 
-### Verb-described operations  -  -ed/-ing suffix
+- **Mutating** operations are imperative verb phrases: `sort()`,
+  `append(newElement)`, `remove(at:)`, `invalidate()`.
+- **Non-mutating** operations read as noun phrases, adjective phrases or a
+  description of what comes back: `distance(to:)`, `intersection(_:)`,
+  `trimmingCharacters(in:)`.
+- **Booleans** should state something true or false about the receiver: `isEmpty`,
+  `contains(_:)`, `isFileURL`. Avoid `empty` (verb or adjective?) and
+  `includes` (an unfinished phrase).
 
-When the operation is naturally described by a verb:
-- **Mutating:** imperative verb (`sort`, `append`, `reverse`)
-- **Nonmutating:** past participle `-ed` or present participle `-ing`
+### Mutating and non-mutating pairs
 
-Default to `-ed` (past participle) when the phrase naturally describes the returned value. Use `-ing` (present participle) only when the `-ed` form is ungrammatical or describes the direct object rather than the returned receiver or result. A direct object is a clue to check the grammar, not the rule by itself.
+When both forms exist, name them as a pair.
 
-| Mutating | Nonmutating | Why |
-|----------|-------------|-----|
-| `sort()` | `sorted()` | `-ed`  -  "a sorted array" |
-| `reverse()` | `reversed()` | `-ed`  -  "a reversed collection" |
-| `sortLines()` | `sortedLines()` | `-ed`  -  "sorted lines" describes the result |
-| `append(y)` | `appending(y)` | `-ing`  -  `appended` does not describe the returned receiver clearly |
-| `stripNewlines()` | `strippingNewlines()` | `-ing`  -  direct-object pattern from the guidelines |
+**Verb operations.** The mutating form is the imperative verb. The
+non-mutating form adds `-ed` by default, when "a [verb]-ed [noun]" describes
+the result. Fall back to `-ing` only when `-ed` is ungrammatical or would
+describe the direct object instead of the returned value. A direct object is a
+hint to run that grammar check, not a rule by itself.
 
-### Noun-described operations  -  form- prefix
+| Mutating | Non-mutating | Why |
+|---|---|---|
+| `sort()` | `sorted()` | `-ed` default |
+| `reverse()` | `reversed()` | `-ed` default |
+| `sortLines()` | `sortedLines()` | `-ed` describes the result |
+| `append(y)` | `appending(y)` | `appended` would not describe the returned receiver |
+| `stripNewlines()` | `strippingNewlines()` | `-ed` would name the removed newlines |
 
-When the operation is naturally described by a noun:
-- **Nonmutating:** the noun itself (`union`, `intersection`)
-- **Mutating:** `form` prefix (`formUnion`, `formIntersection`)
+**Noun operations.** The non-mutating form is the noun; the mutating form
+takes a `form` prefix:
 
 ```swift
-// Nonmutating  -  returns new value
-let combined = a.union(b)
-
-// Mutating  -  modifies in place
-a.formUnion(b)
+let both = weekdays.union(weekend)     // new value
+weekdays.formUnion(weekend)            // in place
 ```
 
-### Factory methods  -  make- prefix
-
-Factory methods that create a new value start with `make`.
-
-```swift
-let iterator = collection.makeIterator()
-let buffer = parser.makeBuffer()
-```
-
-In mixed routing answers, briefly validate existing `make...` factory names before handing off unrelated type-system or linting details to sibling skills.
-
-### Pair decision table
-
-| Operation described by | Mutating name | Nonmutating name | Example pair |
-|------------------------|---------------|-------------------|-------------|
-| Verb (default) | verb | verb + `-ed` | `sort()` / `sorted()` |
-| Verb (`-ed` is ungrammatical) | verb | verb + `-ing` | `stripNewlines()` / `strippingNewlines()` |
-| Noun | `form` + Noun | noun | `formUnion(b)` / `union(b)` |
-
-For the full -ed/-ing decision tree and expanded naming patterns, see [references/side-effects-and-mutating-pairs.md](references/side-effects-and-mutating-pairs.md).
+| Kind | Mutating | Non-mutating |
+|---|---|---|
+| Verb (default) | verb | verb + `-ed` |
+| Verb where `-ed` fails | verb | verb + `-ing` |
+| Noun | `form` + Noun | noun |
 
-## Documentation Comments
+**Factories** get a `make` prefix whenever they produce a fresh value: `makeIterator()`,
+`makeBuffer()`. If a mixed request already uses `make...` names, confirm them
+in a line before routing the rest.
 
-Every public declaration must have a documentation comment.
+Decision tree, `form` rules, Boolean and factory patterns:
+[the side-effects reference](references/side-effects-and-mutating-pairs.md).
 
-### Summary rules by declaration kind
+## Documentation comments
 
-| Declaration | Summary describes |
-|-------------|-------------------|
-| Function / method | What it does and what it returns |
-| Subscript | What it accesses |
-| Initializer | What it creates |
-| Type / property / variable | What it **is** |
+Every public declaration gets one. The summary is a single sentence fragment
+ending in a period, starting with a verb for actions and a noun phrase for
+entities. What it says depends on the declaration:
 
-Write summaries as a single sentence fragment, beginning with a verb (for actions) or a noun phrase (for entities), ending in a period.
+| Declaration | Summary says |
+|---|---|
+| function or method | the action and its result |
+| subscript | what it accesses |
+| initializer | what it creates |
+| type, property, variable | the thing itself |
 
 ```swift
-/// Returns the element at the specified index.
-func element(at index: Int) -> Element { ... }
+protocol ReadingLog {
+    /// Returns the reading closest to `time`, or `nil` if there are none.
+    func reading(nearest time: Date) -> Reading?
 
-/// The number of elements in the collection.
-var count: Int { ... }
+    /// The number of readings recorded today.
+    var todayCount: Int { get }
 
-/// Creates a new array with the given elements.
-init(_ elements: some Sequence<Element>) { ... }
+    /// Creates a log that keeps at most `limit` readings.
+    init(limit: Int)
 
-/// Accesses the element at the specified position.
-subscript(index: Int) -> Element { ... }
+    /// Accesses the reading at `position`.
+    subscript(position: Int) -> Reading { get }
+}
 ```
 
-### Symbol markup
-
-Use standard symbol markup after the summary when relevant:
-
-- `- Parameter name:` for individual parameters
-- `- Parameters:` block for multiple parameters
-- `- Returns:` for the return value
-- `- Throws:` for errors thrown
-- `- Complexity:` for algorithmic complexity
+After the summary, use symbol markup: `- Parameter name:`, a `- Parameters:`
+block, `- Returns:`, `- Throws:`, `- Complexity:`.
 
 ```swift
-/// Removes and returns the element at the specified position.
-///
-/// - Parameter index: The position of the element to remove.
-/// - Returns: The removed element.
-/// - Complexity: O(*n*), where *n* is the length of the collection.
-mutating func remove(at index: Int) -> Element { ... }
+protocol EditableReadingLog: ReadingLog {
+    /// Removes the reading at `position` and hands it back.
+    ///
+    /// - Parameter position: The index of the reading to remove. Must be a
+    ///   valid index of the log.
+    /// - Returns: The reading that was removed.
+    /// - Complexity: O(*n*) in the log's length.
+    @discardableResult
+    mutating func remove(at position: Int) -> Reading
+}
 ```
 
-### O(1) complexity rule
-
-Document the complexity of any computed property that is not O(1). Callers assume properties are O(1) by default. If a property does more than constant-time work, state the complexity explicitly.
+A property looks free to call, so readers expect constant time. When a computed
+property costs more, the doc comment has to say so:
 
 ```swift
-/// The total weight of all items.
+/// The combined mass of every item in the crate.
 ///
-/// - Complexity: O(*n*), where *n* is the number of items.
-var totalWeight: Double {
-    items.reduce(0) { $0 + $1.weight }
+/// - Complexity: O(*n*) in the item count.
+var totalMass: Measurement<UnitMass> {
+    items.map(\.mass).reduce(Measurement(value: 0, unit: .kilograms), +)
 }
 ```
 
-For documentation patterns and examples, see [references/conventions-and-special-rules.md](references/conventions-and-special-rules.md).
-
-## Clarity and Naming
-
-Clarity at the point of use is the most important goal. Every design decision serves the person reading a call site.
-
-**Clarity over brevity.** Longer names are acceptable when they remove ambiguity. Do not abbreviate.
-
-```swift
-// GOOD
-employees.remove(at: position)
-
-// BAD  -  ambiguous: remove the element? remove at position?
-employees.remove(position)
-```
-
-**Include words needed to avoid ambiguity.** If omitting a word makes the call site unclear, keep it.
-
-```swift
-// GOOD  -  "at" clarifies the argument's role
-friends.remove(at: index)
-
-// BAD  -  is "index" the element to remove or the position?
-friends.remove(index)
-```
-
-**Omit needless words.** Do not repeat type information already available from the context.
-
-```swift
-// GOOD
-allViews.remove(cancelButton)
-
-// BAD  -  "Element" repeats the type
-allViews.removeElement(cancelButton)
-```
-
-**Name variables and parameters by role, not type.** Use the entity's role in the current context, not its type name.
-
-```swift
-// GOOD  -  describes the role
-var greeting: String
-func add(_ observer: NSObject, for keyPath: String)
-
-// BAD  -  names the type
-var string: String
-func add(_ object: NSObject, for string: String)
-```
-
-**Compensate for weak type information.** When a parameter type is `Any`, `AnyObject`, or a fundamental type like `Int` or `String`, add role-clarifying words to the name.
-
-```swift
-// GOOD  -  role is clear despite weak types
-func addObserver(_ observer: NSObject, forKeyPath path: String)
-
-// BAD  -  what does "string" mean here?
-func add(_ object: NSObject, for string: String)
-```
-
-For extended naming examples and patterns, see [references/naming-and-clarity.md](references/naming-and-clarity.md).
-
-## Fluent Usage and Protocols
-
-**Call sites read as grammatical English.** Prefer names that form grammatical phrases at the point of use.
-
-```swift
-// GOOD  -  reads fluently
-x.insert(y, at: z)          // "x, insert y at z"
-x.subviews.remove(at: i)    // "x's subviews, remove at i"
-x.makeIterator()             // "x, make iterator"
-
-// BAD  -  ungrammatical
-x.insert(y, position: z)
-x.subviews.remove(i)
-```
-
-**Initializer first argument.** The first argument to an initializer should not form a phrase continuing the type name.
-
-```swift
-// GOOD
-let foreground = Color(red: 32, green: 64, blue: 128)
-
-// BAD  -  "Color with red" reads awkwardly
-let foreground = Color(havingRGBValuesRed: 32, green: 64, blue: 128)
-```
-
-**Protocol naming conventions:**
-
-| Protocol describes | Naming pattern | Examples |
-|--------------------|----------------|----------|
-| What something **is** | Noun | `Collection`, `IteratorProtocol` |
-| A **capability** | `-able`, `-ible`, or `-ing` suffix | `Equatable`, `Hashable`, `Sendable` |
-
-## General Conventions
-
-**Casing.** Types and protocols use `UpperCamelCase`. Everything else uses `lowerCamelCase`. Acronyms that are commonly all-caps in American English appear uniformly upper- or lower-cased based on position.
-
-```swift
-var utf8Bytes: [UTF8.CodeUnit]
-var isRepresentableAsASCII = true
-var userSMTPServer: SMTPServer
-```
-
-**Methods and properties over free functions.** Prefer methods and properties. Use free functions only when:
-1. There is no obvious `self`  -  `min(x, y)`
-2. The function is an unconstrained generic  -  `print(value)`
-3. The function syntax is established domain notation  -  `sin(x)`
-
-**Default arguments over method families.** Prefer a single method with default parameters over a family of methods that differ only in which parameters they accept. Place defaulted parameters at the end. Parameters with default values should always have argument labels  -  defaulted parameters are usually omitted at call sites, so their labels must be clear when they do appear.
-
-```swift
-// GOOD  -  labeled with defaults
-func decode(_ data: Data, encoding: String.Encoding = .utf8) -> String?
-
-// BAD  -  method family
-func decode(_ data: Data) -> String?
-func decode(_ data: Data, encoding: String.Encoding) -> String?
-```
-
-**Overload safety.** Methods may share a base name when they operate in different type domains or when their meaning is clear from context. Avoid return-type-only overloads that cause ambiguity at the call site.
-
-For casing edge cases, overload patterns, and tuple/closure naming, see [references/conventions-and-special-rules.md](references/conventions-and-special-rules.md).
-
-## Common Mistakes
-
-1. **Omitting needed argument labels.** Using `remove(position)` instead of `remove(at: position)` when the role of the argument is ambiguous without the label.
-
-2. **Using -ed when -ing is correct.** Applying `stripped()` when the past participle is ungrammatical  -  use `stripping()` instead. Test: does "a [verb]-ed [noun]" read naturally?
-
-3. **Using verb names for side-effect-free operations.** Naming a nonmutating method `sort()` that returns a new collection  -  use `sorted()` to signal no mutation.
-
-4. **Naming by type instead of role.** Using `string` instead of `greeting`, or `array` instead of `elements`, when the role would be more informative.
-
-5. **Missing documentation comments.** Leaving public declarations undocumented, or writing summaries that describe the implementation rather than the purpose.
-
-6. **Not documenting non-O(1) computed properties.** Exposing a linear-time computed property without a `Complexity:` note, causing callers to assume O(1) and use it in loops.
-
-7. **Applying form- prefix to verb-based operations.** Writing `formSort()` instead of just `sort()`  -  the `form` prefix is only for noun-based operations (`formUnion`).
-
-8. **Factory methods without make- prefix.** Naming factory methods as `createIterator()` or `buildBuffer()` instead of `makeIterator()` and `makeBuffer()`.
-
-9. **Repeating type information in names.** Writing `removeElement(cancelButton)` or `stringValue: String` when the type is already evident from context.
-
-10. **Return-type-only overloads.** Defining overloads that differ only in return type, creating ambiguity when the compiler cannot infer the expected type.
-
-11. **Unlabeled tuple members and closure parameters.** Exposing tuples or closures in public API without naming their components, forcing callers to use positional access.
-
-## Review Checklist
-
-### Argument Labels
-- [ ] First argument follows the correct label rule (grammatical phrase, prepositional, conversion, or labeled)
-- [ ] Prepositional labels do not incorrectly group independent arguments
-- [ ] Value-preserving conversion initializers omit the first label
-- [ ] All non-special-case arguments have labels
-
-### Naming Semantics
-- [ ] Mutating methods use imperative verb form
-- [ ] Nonmutating methods use -ed/-ing or noun form
-- [ ] Mutating/nonmutating pairs follow the correct pattern (verb pair or noun/form-noun pair)
-- [ ] Boolean properties read as assertions (`isEmpty`, `isValid`, `contains`)
-- [ ] Variables and parameters are named by role, not type
-
-### Documentation
-- [ ] Every public declaration has a doc comment
-- [ ] Summaries are single sentence fragments ending in a period
-- [ ] Summaries describe the correct thing per declaration kind (action, access, creation, entity)
-- [ ] Non-O(1) computed properties document their complexity
-- [ ] Parameters, return values, and thrown errors are documented with symbol markup
-
-### Conventions
-- [ ] Types and protocols use UpperCamelCase; everything else uses lowerCamelCase
-- [ ] Acronyms are uniformly cased based on position
-- [ ] Default arguments are preferred over method families
-- [ ] Overloads do not differ only in return type
-- [ ] Protocol names follow the noun (is-a) or suffix (capability) convention
+## Clarity
+
+The top priority is how the call reads where it is used; every other choice
+serves that reader.
+
+- **Clarity beats brevity.** A longer name that removes doubt is better. Do not
+  abbreviate. `remove(at: position)` says what `remove(position)` leaves open.
+- **Include the words needed to avoid ambiguity.**
+  `friends.remove(at: index)`, not `friends.remove(index)`.
+- **Omit words that only repeat type information.**
+  `allViews.remove(cancelButton)`, not `allViews.removeElement(cancelButton)`.
+- **Name by role, not type.** `var greeting: String`, not `var string: String`;
+  `track(_ subscriber: Subscriber, for topic: String)`, not
+  `track(_ object: Subscriber, for string: String)`.
+- **Compensate for weak types.** When a parameter is `Any`, `AnyObject`, `Int`
+  or `String`, the type says little; add a role word, as in
+  `addObserver(_:forKeyPath:)`, where `forKeyPath` explains the `String`.
+
+Examples and terminology: [the naming reference](references/naming-and-clarity.md).
+
+## Fluent call sites and protocols
+
+Call sites should read as grammatical English: `insert(y, at: z)`,
+`subviews.remove(at: i)`, `makeIterator()`. Not `insert(y, position: z)` or
+`subviews.remove(i)`.
+
+An initializer's first argument should not continue the type name as a
+phrase: `Color(red:green:blue:)`, not `Color(havingRGBValuesRed:green:blue:)`.
+
+Protocols:
+
+- that say what something **is** are nouns: `Collection`, `IteratorProtocol`;
+- that describe a **capability** end in `-able`, `-ible` or `-ing`:
+  `Equatable`, `Hashable`, `Sendable`.
+
+Generic parameters follow the role rule too: `Element`, `Key`, `Value`,
+`Base` when the parameter has a meaning in the API; a single letter such as
+`T` only when it has none. Details in
+[the naming reference](references/naming-and-clarity.md).
+
+## Conventions
+
+- Types and protocols are `UpperCamelCase`; everything else is
+  `lowerCamelCase`.
+- Acronyms that are usually all capitals in American English are all upper or
+  all lower case depending on position: `utf8Bytes`, `isRepresentableAsASCII`,
+  `userSMTPServer`.
+- Reach for a method or property before a free function. A free function fits
+  in three cases only: nothing is naturally `self` (`max(a, b)`), the function is
+  an unconstrained generic (`print(value)`), or the notation is established
+  in the domain (`sin(x)`).
+- Give one method defaulted parameters rather than writing several methods
+  that vary only in the parameter list. Put defaulted parameters at the
+  end, and give them labels: they are usually left out, so when present they
+  must explain themselves.
+
+  ```swift
+  // One entry point
+  func render(_ page: Page, scale: Double = 1, includesMargins: Bool = true) -> Image {
+      PageRasterizer(scale: scale, margins: includesMargins).draw(page)
+  }
+
+  // Not a family such as render(_:), render(_:scale:) and
+  // render(_:scale:includesMargins:)
+  ```
+
+- Two overloads can use one base name if they act on different kinds of types
+  or the shared meaning is obvious. Never overload on return type alone.
+
+Casing tables, complexity, free functions, overloads, tuples and closures:
+[the conventions reference](references/conventions-and-special-rules.md).
+
+## Common mistakes
+
+1. Dropping a needed label: `friends.remove(i)` where `friends.remove(at: i)`
+   is meant.
+2. `-ed` where `-ing` is right: `stripped()` rather than `stripping()`. Test
+   whether "a [verb]-ed [noun]" reads naturally.
+3. A verb for a side-effect-free operation: a non-mutating `sort()` should be
+   `sorted()`.
+4. Naming by type: `string` for `greeting`, `array` for `elements`.
+5. No doc comment, or a summary that describes the implementation instead of
+   the purpose.
+6. An expensive computed property with no complexity note, so callers use it in
+   a loop.
+7. `form` on a verb operation (`formSort()`); `form` is for noun operations
+   only.
+8. Factories without `make`: `createIterator()`, `buildBuffer()`.
+9. Repeating type information: `removeElement(cancelButton)`,
+   `stringValue: String`.
+10. Overloads that differ only by return type, which confuse inference.
+11. Unlabelled tuple members or closure parameters in public API, forcing
+    `.0` and `.1`.
+
+## Review checklist
+
+Argument labels
+
+- [ ] The first argument follows the right rule: grammatical phrase,
+      prepositional, conversion, or labelled
+- [ ] Prepositional labels do not tie together arguments that are independent
+- [ ] Lossless conversion initializers take an unlabelled first argument
+- [ ] Every argument not covered by a special rule has a label
+
+Naming
+
+- [ ] Mutating operations are imperative verbs
+- [ ] Non-mutating operations use `-ed`, `-ing` or a noun
+- [ ] Pairs follow the verb pattern or the noun / `form`-noun pattern
+- [ ] Boolean names state a fact: `isEmpty`, `isValid`, `contains`
+- [ ] Names describe roles, not types
+
+Documentation
+
+- [ ] Every public declaration is documented
+- [ ] Each summary is one sentence fragment with a closing period
+- [ ] The summary fits the declaration: action, access, creation or entity
+- [ ] Non-O(1) computed properties state their complexity
+- [ ] Symbol markup covers parameters, the return value and thrown errors
+
+Conventions
+
+- [ ] `UpperCamelCase` for types and protocols, `lowerCamelCase` for the rest
+- [ ] Acronyms are cased uniformly by position
+- [ ] Defaulted parameters instead of method families
+- [ ] No overloads that differ only by return type
+- [ ] Protocol names are nouns (what it is) or carry a capability suffix
 
 ## References
 
-- Naming clarity, role-based naming, weak-type compensation, and terminology: [references/naming-and-clarity.md](references/naming-and-clarity.md)
-- Argument label edge cases, parameter naming, and default argument strategy: [references/argument-labels-and-parameters.md](references/argument-labels-and-parameters.md)
-- Side-effect naming examples, -ed/-ing decision tree, form- prefix patterns, and factory methods: [references/side-effects-and-mutating-pairs.md](references/side-effects-and-mutating-pairs.md)
-- Casing edge cases, complexity documentation, overload safety, tuple/closure naming, and free function exceptions: [references/conventions-and-special-rules.md](references/conventions-and-special-rules.md)
+- [Argument labels and parameters](references/argument-labels-and-parameters.md):
+  prepositional edge cases, grammatical-phrase examples, conversion kinds,
+  parameter names for documentation, default arguments and ordering.
+- [Naming and clarity](references/naming-and-clarity.md): needed and needless
+  words, role naming, weak types, method versus property, generic parameter
+  names, terminology.
+- [Side effects and mutating pairs](references/side-effects-and-mutating-pairs.md):
+  in-place and copying examples, how to pick `-ed` or `-ing`, the `form`
+  prefix, Booleans, `make` factories.
+- [Conventions and special rules](references/conventions-and-special-rules.md):
+  casing and acronyms, complexity notes, free-function exceptions, overload
+  safety, tuple and closure naming, unconstrained polymorphism.