Swift 设计指南之 编程规范

/// 返回 `self` 的  "view"，其中包含顺序相反的相同元素。
func reversed() -> ReverseCollection

/// 在 `self` 的起始处插入 `newHead` 。
mutating func prepend(newHead: Int)

/// 返回一个由 `head` 和 `self` 依次组成的 `List` 。
func prepending(head: Element) -> List

/// 如果不空，这返回`self`的第一个元素，
/// 否则返回 `nil`。
mutating func popFirst() -> Element?

/// 访问第 `index` 个元素。
subscript(index: Int) -> Element { get set }

/// 创建一个包含 `n` 个 `x` 的实例。
init(count n: Int, repeatedElement x: Element)

/// 支持任意位置高效插入删除元素的列表
struct List {

  /// 元素从 `self` 开始，若 self 为空则为 `nil`
  var first: Element?
  ...

/// Writes the textual representation of each    ←  摘要
/// element of `items` to the standard output.
///                                              ← 空行
/// The textual representation for each item `x` ← 扩展描述
/// is generated by the expression `String(x)`.
///
/// - Parameter separator: text to be printed    ?
///   between items.                             ?
/// - Parameter terminator: text to be printed   ? 参数区
///   at the end.                                ?
///                                              ?
/// - Note: To print without a trailing          ?
///   newline, pass `terminator: ""`             ?
///                                              ? 标识与其相关的命令
/// - SeeAlso: `CustomDebugStringConvertible`,   ?
///   `CustomStringConvertible`, `debugPrint`.   ?
public func print(
  items: Any..., separator: String = " ", terminator: String = "\n")

?
extension List {
  public mutating func remove(at position: Index) -> Element
}
employees.remove(at: x)

??
employees.remove(x) // 不明确: 我们是在删除 x 吗?

??
public mutating func removeElement(member: Element) -> Element?
allViews.removeElement(cancelButton)

?
public mutating func remove(member: Element) -> Element?
allViews.remove(cancelButton) // 更明了

??
var string = "Hello"
protocol ViewController {
  associatedtype ViewType : View
}
class ProductionLine {
  func restock(from widgetFactory: WidgetFactory)
}

?
var greeting = "Hello"
protocol ViewController {
  associatedtype ContentView : View
}
class ProductionLine {
  func restock(from supplier: WidgetFactory)
}

protocol Sequence {
  associatedtype IteratorType : Iterator
}

??
func add(observer: NSObject, for keyPath: String)
grid.add(self, for: graphics) // vague

?
func addObserver(_ observer: NSObject, forKeyPath path: String)
grid.addObserver(self, forKeyPath: graphics) // clear

?
x.insert(y, at: z)          “x, insert y at z”
x.subViews(havingColor: y)  “x‘s subviews having color y”
x.capitalizingNouns()       “x, capitalizing nouns”

??
x.insert(y, position: z)
x.subViews(color: y)
x.nounCapitalize()

AudioUnit.instantiate(
  with: description,
  options: [.inProcess], completionHandler: stopProgressBar)

?
let foreground = Color(red: 32, green: 64, blue: 128)
let newPart = factory.makeWidget(gears: 42, spindles: 14)

??
let foreground = Color(havingRGBValuesRed: 32, green: 64, andBlue: 128)
let newPart = factory.makeWidget(havingGearCount: 42, andSpindleCount: 14)

let rgbForeground = RGBColor(cmykForeground)

/// Reverses `self` in-place.
mutating func reverse()
/// Returns a reversed copy of `self`.
func reversed() -> Self
...
x.reverse()
let y = x.reversed()

/// Strips all the newlines from \`self\`
mutating func stripNewlines()
/// Returns a copy of \`self\` with all the newlines stripped.
func strippingNewlines() -> String
...
s.stripNewlines()
let oneLine = t.strippingNewlines()

min(x, y, z)

print(x)

sin(x)

var utf8Bytes: [UTF8.CodeUnit];
var isRepresentableAsASCII = true;
var userSMTPServer: SecureSMTPServer;

var radarDetector: RadarScanner;
var enjoysScubaDiving = true;

?
extension Shape {
  /// Returns `true` iff `other` is within the area of `self`.
  func contains(other: Point) -> Bool { ... }

  /// Returns `true` iff `other` is entirely within the area of `self`.
  func contains(other: Shape) -> Bool { ... }

  /// Returns `true` iff `other` is within the area of `self`.
  func contains(other: LineSegment) -> Bool { ... }
}

?
extension Collection where Element : Equatable {
  /// Returns `true` iff `self` contains an element equal to
  /// `sought`.
  func contains(sought: Element) -> Bool { ... }
}

??
extension Database {
  /// Rebuilds the database‘s search index
  func index() { ... }

  /// Returns the `n`th row in the given table.
  func index(n: Int, inTable: TableID) -> TableRow { ... }
}

??
extension Box {
  /// 如果有值，返回 `Int` 并保存在 `self`
  /// 否则返回 `nil`
  func value() -> Int? { ... }

  /// 如果有值，返回 `String` 并保存在 `self`
  /// 否则返回 `nil`
  func value() -> String? { ... }
}

func move(from start: Point, to end: Point)

?
/// Return an `Array` containing the elements of `self`
/// that satisfy `predicate`.
func filter(_ predicate: (Element) -> Bool) -> [Generator.Element]

/// Replace the given `subRange` of elements with `newElements`.
mutating func replaceRange(_ subRange: Range, with newElements: [E])

??
/// Return an `Array` containing the elements of `self`
/// that satisfy `includedInResult`.
func filter(_ includedInResult: (Element) -> Bool) -> [Generator.Element]

/// Replace the range of elements indicated by `r` with
/// the contents of `with`.
mutating func replaceRange(_ r: Range, with: [E])

??
let order = lastName.compare(
royalFamilyName, options: [], range: nil, locale: nil)

?
let order = lastName.compare(royalFamilyName)

?
extension String {
  /// ...描述...
  public func compare(
     other: String, options: CompareOptions = [],
     range: Range? = nil, locale: Locale? = nil
  ) -> Ordering
}

??
extension String {
  /// ...描述 1...
  public func compare(other: String) -> Ordering
  /// ... 描述 2...
  public func compare(other: String, options: CompareOptions) -> Ordering
  /// ... 描述 3...
  public func compare(
     other: String, options: CompareOptions, range: Range) -> Ordering
  /// ... 描述 4...
  public func compare(
     other: String, options: StringCompareOptions,
     range: Range, locale: Locale) -> Ordering
}

func move(from start: Point, to end: Point)
x.move(from: x, to: y)

extension String {
  // 将 `x` 转换为给定进制下的文本表示
  init(_ x: BigInt, radix: Int = 10)   ← 注意起始的下划线
}

text = "值为: "
text += String(veryLargeNumber)
text += "十六进制为: "
text += String(veryLargeNumber, radix: 16)

extension UInt32 {
  /// 创建一个精确类型的实例 `value`
  init(_ value: Int16)            ← 精度更宽，因此没有标签
  /// 创建最低有 32 位的实例 `source`。
  init(truncating source: UInt64)
  /// 创建最接近描述  `valueToApproximate` 近似值的实例
  init(saturating valueToApproximate: UInt64)
}

??
a.move(toX: b, y: c)
a.fade(fromRed: b, green: c, blue: d)

?
a.moveTo(x: b, y: c)
a.fadeFrom(red: b, green: c, blue: d)

?
view.dismiss(animated: false)
let text = words.split(maxSplits: 12)
let studentsByName = students.sorted(isOrderedBefore: Student.namePrecedes)

??
view.dismiss(false)   不 dismiss? Dismiss 一个 Bool 值?
words.split(12)       分割数字 12?

/// 确保我们至少持有并唯一引用 `requestedCapacity` 元素。
///
/// 若需要更多存储空间， `allocate` 会被调用
/// `byteCount` 等于最大对齐的内存单元数
///
/// - Returns:
///   - reallocated: 当且仅当分配新内存区为 `true`
///   - capacityChanged: 当且仅当 `capacity` 被更新时为 `true`
mutating func ensureUniqueStorage(
  minimumCapacity requestedCapacity: Int,
  allocate: (byteCount: Int) -> UnsafePointer<Void>
) -> (reallocated: Bool, capacityChanged: Bool)

allocate(byteCount: newCount * elementSize)

??
struct Array {
  /// 在 `self.endIndex` 插入 `newElement`
  public mutating func append(newElement: Element)

  /// 在 `self.endIndex` 顺序插入 `newElements` 的内容
  public mutating func append<
    S : SequenceType where S.Generator.Element == Element
  >(newElements: S)
}

??
var values: [Any] = [1, "a"]
values.append([2, 3, 4]) // [1, "a", [2, 3, 4]] 还是 [1, "a", 2, 3, 4]?

?
struct Array {
  /// Inserts `newElement` at `self.endIndex`.
  public mutating func append(newElement: Element)

  /// Inserts the contents of `newElements`, in order, at
  /// `self.endIndex`.
  public mutating func append<
    S : SequenceType where S.Generator.Element == Element
  >(contentsOf newElements: S)
}