@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-api-design-guidelines/references/side-effects-and-mutating-pairs.md

@@ -1,158 +1,115 @@
 # Side Effects and Mutating Pairs
 
-Extended examples for side-effect naming, the -ed/-ing decision tree, form- prefix patterns, Boolean naming, and factory methods.
+Naming that tells the caller, at a glance, whether an operation changes the
+receiver.
 
-## Contents
+## Examples by kind
 
-- [Side-Effect Naming Extended Examples](#side-effect-naming-extended-examples)
-- [The -ed/-ing Decision Tree](#the--ed-ing-decision-tree)
-- [Form- Prefix Patterns](#form--prefix-patterns)
-- [Boolean Naming Patterns](#boolean-naming-patterns)
-- [Factory Method Naming](#factory-method-naming)
-
-## Side-Effect Naming Extended Examples
-
-### Mutating  -  imperative verbs
-
-Methods that change the receiver's state use imperative verb form.
+Mutating: imperative verbs.
 
 ```swift
-array.sort()
-array.append(newElement)
-array.removeAll()
-set.insert(member)
-dictionary.updateValue(newValue, forKey: key)
-buffer.replaceSubrange(range, with: newElements)
+scores.sort()
+scores.append(97)
+scores.removeAll()
+names.insert("Rin")
+ranks.updateValue(3, forKey: "Rin")
+letters.replaceSubrange(0..<2, with: ["x", "y"])
 ```
 
-### Nonmutating  -  nouns, past participles, descriptions
-
-Methods that return a value without changing the receiver use a form that describes the result.
+Non-mutating: nouns, participles or descriptions of the result.
 
 ```swift
-let sorted = array.sorted()
-let distance = point.distance(to: origin)
-let trimmed = string.trimmingCharacters(in: .whitespaces)
-let union = setA.union(setB)
-let successor = index.advanced(by: 1)
-let prefix = array.prefix(3)
+let ordered = scores.sorted()
+let gap = start.distance(to: end)
+let clean = input.trimmingCharacters(in: .whitespaces)
+let everyone = morningShift.union(eveningShift)
+let next = index.advanced(by: 1)
+let podium = ordered.prefix(3)
 ```
 
-### Mixed  -  same type, both variants
-
-When both exist, the naming makes the difference obvious at every call site.
+One type can offer both forms of several operations; the names alone show which
+calls change it:
 
 ```swift
-// Mutating
-array.sort()
-// Nonmutating  -  returns new value
-let newArray = array.sorted()
-
-// Mutating
-set.formUnion(other)
-// Nonmutating  -  returns new value
-let combined = set.union(other)
-```
-
-## The -ed/-ing Decision Tree
-
-Use this decision tree to choose between `-ed` and `-ing` for the nonmutating variant of a verb-described operation.
-
-**Step 1: Try the past participle (`-ed`).** Read the phrase: "a [verb]-ed [noun]". If it sounds grammatical, use `-ed`.
+var tags: Set<String> = ["swift", "ios"]
+tags.formUnion(["macos"])                        // changes tags
+let preview = tags.union(["visionos"])           // tags unchanged
 
-```
-sort → sorted          ✓  "a sorted array" sounds correct
-sortLines → sortedLines ✓ "sorted lines" describes the result
-reverse → reversed      ✓ "a reversed collection" sounds correct
-shuffle → shuffled      ✓ "a shuffled deck" sounds correct
+var queue = ["c", "a", "b"]
+queue.sort()                                     // changes queue
+let snapshot = queue.sorted(by: >)               // queue unchanged
 ```
 
-**Step 2: Does -ed fail the result-description test?**
+## Choosing between -ed and -ing
 
-Use the present participle (`-ing`) 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.
+1. **Try `-ed`.** Say "a [verb]-ed [noun]". If it is grammatical and describes
+   the returned value, use it: `sorted`, `sortedLines`, `reversed`, `shuffled`.
+2. **Otherwise use `-ing`.** Use it when `-ed` does not parse, or when it
+   would describe the direct object rather than the result: `appending`,
+   `strippingNewlines`.
 
-```
-append → appending                  "appended" does not describe the returned receiver clearly
-stripNewlines → strippingNewlines   direct-object pattern from the guidelines
-```
+| Mutating | Non-mutating | Note |
+|---|---|---|
+| `sort()` | `sorted()` | |
+| `reverse()` | `reversed()` | |
+| `shuffle()` | `shuffled()` | |
+| `sortLines()` | `sortedLines()` | "sorted lines" describes the result |
+| `append(_:)` | `appending(_:)` | "an appended collection" misdescribes the receiver |
+| `stripNewlines()` | `strippingNewlines()` | "stripped newlines" would be the removed characters |
+| none | `filter(_:)` | the standard library has only the non-mutating form |
+| none | `drop(while:)` | same |
 
-### Extended -ed/-ing examples and naming patterns
+## The form prefix
 
-| Mutating | Nonmutating | Suffix | Reasoning |
-|----------|-------------|--------|-----------|
-| `sort()` | `sorted()` | -ed | "a sorted array" |
-| `sortLines()` | `sortedLines()` | -ed | "sorted lines" describes the result |
-| `reverse()` | `reversed()` | -ed | "a reversed collection" |
-| `shuffle()` | `shuffled()` | -ed | "a shuffled deck" |
-| `append(_:)` | `appending(_:)` | -ing | `appended` does not describe the returned receiver clearly |
-| `filter(_:)` | `filter(_:)` | n/a | nonmutating only in stdlib |
-| `drop(while:)` | `drop(while:)` | n/a | nonmutating only in stdlib |
+`form` is only for operations named by a noun, where the noun itself is the
+natural non-mutating name.
 
-## Form- Prefix Patterns
+Standard library pairs:
 
-The `form` prefix applies only to noun-described operations where the nonmutating version is the noun itself.
+| Non-mutating | Mutating |
+|---|---|
+| `union(_:)` | `formUnion(_:)` |
+| `intersection(_:)` | `formIntersection(_:)` |
+| `symmetricDifference(_:)` | `formSymmetricDifference(_:)` |
 
-### Standard library examples
+Wrong: `formSort()`, `formAppend(_:)`. Right: `sort()`, `append(_:)`.
 
-| Nonmutating (noun) | Mutating (form- prefix) |
-|---------------------|------------------------|
-| `union(other)` | `formUnion(other)` |
-| `intersection(other)` | `formIntersection(other)` |
-| `symmetricDifference(other)` | `formSymmetricDifference(other)` |
+Why: a noun already names the result, so the in-place version needs some
+other form, and `form` supplies it. A verb already has two forms, the
+imperative and the participle, so it needs no prefix.
 
-### When NOT to use form-
+## Booleans
 
-Do not apply `form` to verb-described operations. The imperative verb form is already the mutating version.
+A Boolean answers yes or no about the receiver, and its name should read as
+that assertion.
 
-```swift
-// WRONG  -  sort is a verb, not a noun
-mutating func formSort()       // ✗
-mutating func sort()           // ✓
+- Adjectives take `is`: `isEmpty`, `isFileURL`, `isSecure`, `isHidden`,
+  `isEnabled`.
+- Verb phrases stand alone: `contains(_:)`, `hasPrefix(_:)`, `canAppend(_:)`.
 
-// WRONG  -  append is a verb
-mutating func formAppend(_:)   // ✗
-mutating func append(_:)       // ✓
+```swift
+if cart.isEmpty { showPlaceholder() }
+if route.contains(stop) { highlight(stop) }
+if session.canResume(from: checkpoint) { resume() }
 ```
 
-The `form` prefix exists because the noun form (`union`) is naturally the nonmutating name, and the mutating version needs a distinct name. Verbs do not have this problem  -  the imperative (`sort`) and participle (`sorted`) are already distinct.
+Avoid:
 
-## Boolean Naming Patterns
-
-Boolean properties and methods read as assertions about the receiver. They answer a yes/no question.
-
-```swift
-// Properties  -  "is" prefix for adjectives
-line.isEmpty
-url.isFileURL
-connection.isSecure
-view.isHidden
-option.isEnabled
-
-// Properties  -  no prefix for verb phrases
-set.contains(element)        // "set contains element"
-string.hasPrefix("https")    // "string has prefix"
-array.canAppend(element)     // "array can append element"
-
-// BAD patterns
-line.empty          // is this a verb ("empty the line") or adjective?
-list.include        // verb or boolean?
-node.leaf           // noun, not an assertion
-```
+- `empty`: reads as either a verb or an adjective.
+- `include`: reads as either an action or a Boolean.
+- `leaf`: a noun, not an assertion; use `isLeaf`.
 
-## Factory Method Naming
+## make factories
 
-Factory methods that create and return a new value use the `make` prefix. This distinguishes them from initializers and from methods that return existing values.
+`make` marks a method that creates a new value, which sets it apart from both
+initializers and methods that return something that already exists:
 
 ```swift
-// GOOD  -  factory creates a new value
-let iterator = collection.makeIterator()
-let buffer = parser.makeBuffer()
-let snapshot = store.makeSnapshot()
-
-// BAD  -  wrong prefix
-let iterator = collection.createIterator()    // use "make"
-let buffer = parser.buildBuffer()             // use "make"
-let snapshot = store.getSnapshot()            // "get" implies retrieval, not creation
+let iterator = playlist.makeIterator()
+let buffer = device.makeBuffer(length: 4096)
+let snapshot = editor.makeSnapshot()
 ```
 
-The `make` prefix signals to callers that the returned value is freshly created, distinct from any cached or shared state.
+Avoid `createIterator()`, `buildBuffer()` and `getSnapshot()`. `get` in
+particular suggests fetching a stored value, not producing a new one. A `make`
+name promises a fresh value that is not cached or shared.