@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-api-design-guidelines/references/conventions-and-special-rules.md

@@ -1,219 +1,147 @@
 # Conventions and Special Rules
 
-Casing conventions, complexity documentation, free function exceptions, overload safety, and tuple/closure naming.
+Casing, complexity notes, when a free function is right, safe overloading,
+labelled tuples and closures, and the traps of unconstrained polymorphism.
 
-## Contents
+## Casing
 
-- [Casing Conventions](#casing-conventions)
-- [Complexity Documentation](#complexity-documentation)
-- [Free Function Exceptions](#free-function-exceptions)
-- [Overload Safety](#overload-safety)
-- [Tuple Member and Closure Parameter Naming](#tuple-member-and-closure-parameter-naming)
-- [Unconstrained Polymorphism](#unconstrained-polymorphism)
+`lowerCamelCase` covers functions, methods, properties, variables, constants,
+enum cases and argument labels. Types and protocols use `UpperCamelCase`.
 
-## Casing Conventions
+Acronyms and initialisms:
 
-Types and protocols use `UpperCamelCase`. Everything else  -  functions, methods, properties, variables, constants, enum cases, argument labels  -  uses `lowerCamelCase`.
+- At the start of a `lowerCamelCase` name, all lower case: `utf8Bytes`,
+  `htmlParser`, `urlSession`.
+- In the middle or at the end, cased to match the position, which in practice
+  means all upper case: `isRepresentableAsASCII`, `userSMTPServer`.
+- In type names, all upper case: `HTTPRequest`, `URLSessionTask`, `UTF8`.
+- Words that began as acronyms but are now ordinary words take normal casing:
+  `radarDetector` / `RadarDetector`, `laserPrinter`, `scubaGear`, never
+  `RADARDetector`.
 
-### Acronym handling
+## Complexity notes
 
-Acronyms that appear as all-uppercase in common American English usage are uniformly upper- or lower-cased based on their position in the name.
+Document the complexity of any computed property or subscript that does more
+than constant work.
 
 ```swift
-// At the start of a lowerCamelCase name  -  all lowercase
-var utf8Bytes: [UTF8.CodeUnit]
-var htmlParser: HTMLParser
-var urlSession: URLSession
-
-// In the middle or end  -  follows the case of its position
-var isRepresentableAsASCII = true
-var userSMTPServer: SMTPServer
-
-// Type names  -  acronym stays uppercase
-struct HTTPRequest { ... }
-class URLSessionTask { ... }
-enum UTF8 { ... }
-```
-
-Words that started as acronyms but are now common words follow standard casing:
-
-```swift
-// These are words, not acronyms
-var radarDetector: RadarDetector   // not "RADARDetector"
-var laserPrinter: LaserPrinter     // not "LASERPrinter"
-var scubaGear: ScubaGear           // not "SCUBAGear"
-```
-
-## Complexity Documentation
-
-Callers assume computed properties are O(1). Document the complexity of any computed property or subscript that does more work.
-
-```swift
-/// The total number of nodes in the tree.
-///
-/// - Complexity: O(*n*), where *n* is the number of nodes.
-var nodeCount: Int {
-    root.descendants.count
+extension Outline {
+    /// The number of headings at every depth.
+    ///
+    /// - Complexity: O(*n*), where *n* is the number of headings in the outline.
+    var headingCount: Int {
+        children.reduce(1) { $0 + $1.headingCount }
+    }
 }
-```
 
-```swift
-/// The element at the given offset from the start.
-///
-/// - Complexity: O(*k*), where *k* is the offset.
-subscript(offset: Int) -> Element {
-    var current = startIndex
-    for _ in 0..<offset { current = index(after: current) }
-    return self[current]
+extension Playlist {
+    /// Accesses the track `offset` positions after the start.
+    ///
+    /// - Complexity: O(*k*), where *k* is `offset`; tracks are walked with
+    ///   `index(after:)`.
+    subscript(offset offset: Int) -> Track {
+        var position = tracks.startIndex
+        for _ in 0..<offset { position = tracks.index(after: position) }
+        return tracks[position]
+    }
 }
 ```
 
-Properties that are genuinely O(1) do not need a complexity note  -  the default assumption is correct.
+Members that really are O(1), such as a stored `count`, `isEmpty` or `first`,
+need no note.
 
-```swift
-// O(1)  -  no note needed
-var count: Int { storage.count }
-var isEmpty: Bool { count == 0 }
-var first: Element? { storage.first }
-```
-
-## Free Function Exceptions
-
-Prefer methods and properties to free functions. Use a free function only when one of these three conditions holds:
-
-**1. No obvious `self`**
+## Free functions
 
-```swift
-// GOOD  -  neither argument is more "self" than the other
-min(x, y)
-max(a, b)
-zip(sequence1, sequence2)
-```
-
-**2. Unconstrained generic**
-
-```swift
-// GOOD  -  works on anything
-print(value)
-debugPrint(value)
-```
+Make it a method unless one of three exceptions applies:
 
-**3. Established domain notation**
+| Exception | Examples |
+|---|---|
+| No obvious `self` | `min`, `max`, `zip` |
+| Unconstrained generic | `print`, `debugPrint` |
+| Established domain notation | `sin`, `cos`, `abs` |
 
 ```swift
-// GOOD  -  mathematical convention
-sin(x)
-cos(x)
-abs(value)
+let d = origin.distance(to: target)          // method
+// not: calculateDistance(from: origin, to: target)
 ```
 
-If none of these apply, make it a method.
-
-```swift
-// BAD  -  has an obvious self
-calculateDistance(from: pointA, to: pointB)
-
-// GOOD
-pointA.distance(to: pointB)
-```
+## Overloads
 
-## Overload Safety
+Sharing a base name is fine when the operations are the same idea with
+different inputs, as with `contains(_:)` and `contains(where:)` on
+`Collection`.
 
-Methods may share a base name when they operate in different type domains or when their meaning is clear from context.
+Overloading on the return type alone is not:
 
 ```swift
-// GOOD  -  different parameter types, same semantic operation
-extension Collection {
-    func contains(_ element: Element) -> Bool
-    func contains(where predicate: (Element) -> Bool) -> Bool
+protocol ConfigReader {
+    func parse() -> Int
+    func parse() -> String
 }
-```
 
-### Avoid return-type-only overloads
-
-Overloads that differ only in return type create ambiguity when the compiler cannot infer the expected type.
-
-```swift
-// BAD  -  ambiguous at call site
-func transform() -> Int { ... }
-func transform() -> String { ... }
-
-let result = transform()  // error: ambiguous
+let result = reader.parse()   // ambiguous: which one?
 ```
 
-### Safe overloading patterns
+Overloads that stay unambiguous differ in their first label or in their
+argument types:
 
 ```swift
-// GOOD  -  different first argument labels disambiguate
-func fetch(id: Int) -> User
-func fetch(name: String) -> User
+protocol AlbumStore {
+    func load(id: Album.ID) async throws -> Album
+    func load(title: String) async throws -> Album
+}
 
-// GOOD  -  different argument types
-func draw(_ rect: CGRect)
-func draw(_ path: CGPath)
+protocol Canvas {
+    func stroke(_ rect: CGRect)
+    func stroke(_ path: CGPath)
+}
 ```
 
-## Tuple Member and Closure Parameter Naming
-
-Label tuple members and closure parameters in public API signatures. Positional access (`.0`, `.1`) is fragile and unreadable.
+## Tuples and closures
 
-### Tuple members
+Label tuple members and closure parameters in public signatures. `.0` and `.1`
+are fragile and say nothing.
 
 ```swift
-// GOOD  -  labeled
-func position() -> (x: Double, y: Double)
-func range() -> (lower: Int, upper: Int)
-
-let pos = item.position()
-pos.x   // clear
-pos.y   // clear
-
-// BAD  -  unlabeled
-func position() -> (Double, Double)
-
-let pos = item.position()
-pos.0   // what is this?
-pos.1   // what is this?
+protocol Chart {
+    func bounds() -> (min: Double, max: Double)      // good
+    func span() -> (start: Date, end: Date)          // good
+    func extent() -> (Double, Double)                // avoid: which is which?
+}
 ```
 
-### Closure parameters
+Closure parameters in higher-order APIs deserve descriptive names too; they
+show up in documentation and completion:
 
-Name closure parameters where they appear in the API, especially for higher-order functions.
+- `filter(_ isIncluded: (Element) throws -> Bool)`
+- `map<T>(_ transform: (Element) throws -> T)`
+- `sort(by areInIncreasingOrder: (Element, Element) throws -> Bool)`
 
-```swift
-// GOOD
-func filter(_ isIncluded: (Element) -> Bool) -> [Element]
-func map<T>(_ transform: (Element) -> T) -> [T]
-func sort(by areInIncreasingOrder: (Element, Element) -> Bool)
-
-// BAD
-func filter(_ predicate: (Element) -> Bool) -> [Element]  // acceptable but less descriptive
-func sort(by compare: (Element, Element) -> Bool)          // "compare" is vague
-```
+`predicate` is acceptable but says less than `isIncluded`; `compare` is vague
+about which order counts as true.
 
-## Unconstrained Polymorphism
+## Unconstrained polymorphism
 
-Be careful with overloads involving `Any`, `AnyObject`, or unconstrained generics. They can silently match when a more specific overload was intended.
+Overloads that take `Any`, `AnyObject` or an unconstrained generic can match
+calls meant for a more specific overload, silently.
 
 ```swift
-// DANGEROUS  -  both overloads match array literals
-struct Container {
-    func append(_ element: Element)
-    func append(_ sequence: some Sequence<Element>)
+struct Batch<Element> {
+    private(set) var items: [Element] = []
+
+    mutating func append(_ element: Element) { items.append(element) }
+    mutating func append(_ elements: some Sequence<Element>) { items.append(contentsOf: elements) }
 }
 
-values.append([2, 3, 4])  // which overload? ambiguous if Element is Array
+var mixed = Batch<Any>()
+mixed.append([1, 2, 3])    // compiles, but is that one new element or three?
+                           // Both overloads accept it; nothing at the call site says which ran.
 ```
 
-Resolve with distinct argument labels:
+Give the collection form its own label:
 
 ```swift
-// GOOD  -  unambiguous
-struct Container {
-    func append(_ element: Element)
-    func append(contentsOf sequence: some Sequence<Element>)
+mutating func append(contentsOf elements: some Sequence<Element>) {
+    items.append(contentsOf: elements)
 }
-
-values.append(singleValue)
-values.append(contentsOf: [2, 3, 4])  // always clear
 ```

package/pipeline/skills/shared/external/swift-api-design-guidelines/references/naming-and-clarity.md

@@ -1,184 +1,146 @@
 # Naming and Clarity
 
-Extended examples for name selection, role-based naming, weak-type compensation, and terminology.
+How to decide which words a name needs, which it can lose, and how to choose
+between a method and a property.
 
-## Contents
+## Words that must stay
 
-- [Include Words Needed for Clarity](#include-words-needed-for-clarity)
-- [Omit Needless Words](#omit-needless-words)
-- [Name by Role Not Type](#name-by-role-not-type)
-- [Compensate for Weak Type Information](#compensate-for-weak-type-information)
-- [Terminology Selection](#terminology-selection)
+Test every call site: would a reader who has never seen the declaration know
+what it does?
 
-## Include Words Needed for Clarity
+| Clear | Ambiguous | What the extra word resolves |
+|---|---|---|
+| `cache.removeValue(forKey: k)` | `cache.remove(k)` | is `k` a key or a value? |
+| `team.member(for: badgeID)` | `team.member(badgeID)` | what the argument identifies |
+| `label.fade(from: previousColor)` | `label.fade(previousColor)` | is it the start or the end colour? |
 
-If omitting a word makes the call site ambiguous, keep it. The test: can a reader unfamiliar with the declaration understand the call site?
+## Words that can go
 
-```swift
-// GOOD  -  "for" distinguishes key lookup from index lookup
-dictionary.removeValue(forKey: key)
-
-// BAD  -  is key the value or the lookup key?
-dictionary.remove(key)
-```
-
-```swift
-// GOOD  -  "for" clarifies the relationship
-extension List {
-    func member(for key: Key) -> Value?
-}
-
-// BAD  -  what is "key" relative to the list?
-extension List {
-    func member(_ key: Key) -> Value?
-}
-```
+A word earns its place only if it adds something the types and context do not
+already say.
 
-```swift
-// GOOD  -  preposition clarifies direction
-view.fade(from: previousColor)
+| Lean | Redundant |
+|---|---|
+| `toolbar.remove(cancelButton)` | `toolbar.removeElement(cancelButton)` |
+| `parser.parse(data)` | `parser.parseData(data)` |
+| `sprite.move(to point: CGPoint)` | `sprite.moveToPoint(_ point: CGPoint)` |
 
-// BAD  -  is this the target or the source?
-view.fade(previousColor)
-```
+## Roles, not types
 
-## Omit Needless Words
+Variables, parameters and associated types should say what part they play,
+not what type they happen to be.
 
-Remove words that merely restate type information. Every word in a name should convey information not already available.
+| Role name | Type name |
+|---|---|
+| `var greeting: String` | `var string: String` |
+| `var bodyText: String` | `var text: String` |
+| `var widthConstraint: NSLayoutConstraint` | `var constraint: NSLayoutConstraint` |
+| `func restock(from supplier: Warehouse)` | `func restock(from warehouse: Warehouse)` |
 
-```swift
-// GOOD
-allViews.remove(cancelButton)
-
-// BAD  -  "Element" repeats the type constraint
-allViews.removeElement(cancelButton)
-```
-
-```swift
-// GOOD
-let result = parser.parse(data)
-
-// BAD  -  "Data" is already the parameter type
-let result = parser.parseData(data)
-```
+Associated types follow the same rule; name them for their meaning in the
+protocol:
 
 ```swift
-// GOOD
-func move(to point: CGPoint)
-
-// BAD  -  "point" is already in the type
-func moveToPoint(_ point: CGPoint)
+protocol Ledger {
+    associatedtype Entry          // good: the role in a ledger
+    associatedtype Index          // good
+}
+// Avoid associatedtype names such as EntryType or IntegerIndex.
 ```
 
-## Name by Role Not Type
+## Generic parameters
 
-Variables, parameters, and associated types should describe the entity's role in the current context.
+Generic parameters are named by role as well. When the parameter means
+something in the API, say it: `Element`, `Key`, `Value`, `Base`, `Destination`.
 
 ```swift
-// GOOD  -  describes the role
-var greeting: String
-var bodyText: String
-let widthConstraint: NSLayoutConstraint
-func restock(from supplier: Warehouse)
-
-// BAD  -  describes the type
-var string: String
-var text: String
-let constraint: NSLayoutConstraint
-func restock(from warehouse: Warehouse)
-```
-
-For associated types in protocols, name by the role in the protocol's semantics:
-
-```swift
-// GOOD
-protocol Container {
-    associatedtype Element
-    associatedtype Index
+struct Pair<First, Second> {
+    var first: First
+    var second: Second
 }
 
-// BAD  -  names the constraint, not the role
-protocol Container {
-    associatedtype ItemType
-    associatedtype IntegerIndex
+protocol Journal {
+    associatedtype Entry
+    mutating func merge<Source: Sequence>(_ source: Source) where Source.Element == Entry
 }
 ```
 
-## Compensate for Weak Type Information
-
-When a parameter type is `Any`, `AnyObject`, `NSObject`, or a fundamental type (`Int`, `String`, `Double`), the call site may lack enough context to convey meaning. Add clarifying words to the name.
+Reach for a single letter (`T`, `U`) only when the parameter has no role worth
+naming, as in a fully generic utility:
 
 ```swift
-// GOOD  -  role words compensate for weak types
-func addObserver(_ observer: NSObject, forKeyPath path: String)
-func fill(with color: UIColor, alpha: Double)
-func setTag(_ tag: Int, for view: UIView)
-
-// BAD  -  weak types make the call site opaque
-func add(_ object: NSObject, for string: String)
-func fill(with any: UIColor, _ value: Double)
-func set(_ value: Int, for object: UIView)
+func swapValues<T>(_ a: inout T, _ b: inout T) { (a, b) = (b, a) }
 ```
 
-For function return types, the same principle applies:
-
-```swift
-// GOOD  -  return context clarifies weak type
-func maximumScore() -> Int
-func playerName() -> String
+Generic parameter names are `UpperCamelCase`, like other types.
 
-// BAD  -  generic return with no context
-func value() -> Int
-func name() -> String
-```
+## Weak types need help
 
-## Terminology Selection
+Some types carry almost no meaning on their own: `Any`, `AnyObject`,
+`NSObject`, and fundamentals such as `Int`, `String` and `Double`. When a
+parameter has one of these types, add a word that states its role.
 
-### Prefer common words over obscure terms
+| Clear | Unclear |
+|---|---|
+| `addObserver(_ observer: NSObject, forKeyPath path: String)` | `add(_ object: NSObject, for string: String)` |
+| `fill(with color: Color, alpha: Double)` | `fill(with any: Any, _ value: Double)` |
+| `setTag(_ tag: Int, for view: UIView)` | `set(_ value: Int, for object: UIView)` |
 
-Use a common English word when it works. Reserve terms of art for situations where the precise technical meaning matters and no common word captures it.
+The same goes for return values:
 
 ```swift
-// GOOD  -  common word suffices
-skin                // not "epidermis"
-beginners           // not "neophytes"
-
-// GOOD  -  term of art is precise and necessary
-func sin(_ angle: Double) -> Double  // "sine" is the term of art
+func highestScore() -> Int      // not value() -> Int
+func captainName() -> String    // not name() -> String
 ```
 
-### Preserve established meanings
+## Method or property
 
-Never use a term of art with a non-standard meaning. Anyone who knows the term expects its conventional definition.
+Properties read as facts about the receiver, and callers treat them as free.
+Choose a property when all of these hold:
 
-```swift
-// GOOD  -  Array is the established term
-struct Array<Element> { ... }
-
-// BAD  -  "List" means something different in CS (linked list)
-struct List<Element> { ... }  // if it's really an array
-```
+- no arguments;
+- no observable side effects;
+- cannot throw or suspend;
+- O(1), or its complexity is documented.
 
-### Avoid abbreviations
+Choose a method when any of these hold:
 
-Do not abbreviate unless the abbreviation is universally understood in the domain. Spell words out.
+- it needs input;
+- it changes state (then it is also a mutating verb);
+- it can fail or must `await`;
+- the cost is large enough that a property would invite misuse, for example
+  a network fetch or a full scan of a large store.
 
 ```swift
-// GOOD
-var backgroundColor: UIColor
-var characterIndex: Int
+struct Inventory {
+    private(set) var items: [Item]
 
-// BAD
-var bgColor: UIColor
-var charIdx: Int
-```
+    var isEmpty: Bool { items.isEmpty }                    // O(1) fact
+    var itemCount: Int { items.count }                     // O(1) fact
 
-### Embrace precedent
+    /// The total stock value.
+    ///
+    /// - Complexity: O(*n*), where *n* is the number of items.
+    var totalValue: Decimal { items.reduce(0) { $0 + $1.price } }   // O(n), documented
 
-Follow naming conventions already established in the ecosystem, even if they conflict with a "purer" design.
+    func items(in category: Category) -> [Item] {           // takes input
+        items.filter { $0.category == category }
+    }
 
-```swift
-// GOOD  -  matches existing Swift/Cocoa convention
-Array, Dictionary, Set       // not Vector, Map, HashSet
-sin(x), cos(x)              // not sine(x), cosine(x)
+    mutating func restock(_ item: Item) { items.append(item) } // changes state
+}
 ```
+
+## Choosing terms
+
+- **Common words first.** Say "skin", not "epidermis"; "beginners", not
+  "neophytes". Keep terms of art for places where their precision matters,
+  such as `sin(_:)`.
+- **Never bend a term of art.** If you use one, use its accepted meaning. An
+  array-backed type should not be called `List`, because readers will expect
+  a linked list.
+- **Avoid abbreviations** unless everyone in the domain uses them:
+  `backgroundColor` and `characterIndex`, not `bgColor` and `charIdx`.
+- **Follow precedent**, even over a design that seems purer. Swift says
+  `Array`, `Dictionary` and `Set`, not `Vector`, `Map` and `HashSet`; `sin` and
+  `cos`, not `sine` and `cosine`.