Swift API Design Guidelines - 1

[1] Foundamentals

사용할 때 명확하게 느끼는 것이 가장 중요합니다.

명확한 것이 간결한 것보다 중요합니다.

let blackButton (👍)
let blackBtn  (👎)

모든 선언에 대해 문서 주석(Documentation Comment) 를 작성해 주세요

/// Writes the textual representation of each  
/// element of `items` to the standard output.
///                                              ← Blank line 빈줄
/// 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   ⎬ Parameters section
///   at the end.                                ⎟
///                                              ⎭
/// - Note: To print without a trailing          ⎫
///   newline, pass `terminator: ""`             ⎟
///                                              ⎬ Symbol commands
/// - SeeAlso: `CustomDebugStringConvertible`,   ⎟
///   `CustomStringConvertible`, `debugPrint`.   ⎭
public func print(_ items: Any..., separator: String = " ", terminator: String = "\n")

[2] Naming

(1) Promote Clear Usage

필요한 단어들을 모두 포함해 두세요

employees.remove(at: x) (👍)
employees.remove(x) (👎)

불필요한 단어를 생략하세요

allViews.removeElement(cancelButton) (👍)
allViews.remove(cancelButton) (👎)

타입 대신 역할에 따라 변수(variables), 파라미터(parameters), 연관타입(associated types)을 네이밍하세요.

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

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

파라미터의 역할을 명확히 하기 위해 불충분한 type 정보를 보충하세요

///Good(👍)
final class MyNotificationCenter{
    private var observers: [String:NSObject] = [:]

    func add(_ observer: NSObject, forKeyPath keyPath: String) {
        observers[keyPath] = observer
    }
}

let center = MyNotificationCenter()
center.add(self, forKeyPat: "mykey")


///Bad(👎)
final class MyNotificationCenter{
    private var observers: [String:NSObject] = [:]

    func add(_ observer: NSObject, for keyPath: String) {
        observers[keyPath] = observer
    }
}

let center = MyNotificationCenter()
center.add(self, for: "key")

(2) Strive for Fluent Usage

method와 function을 영어 문장처럼 사용할 수 있도록 하기

///Good(👍)
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”


///Bad(👎)
x.insert(y, position: z)
x.subViews(color: y)
x.nounCapitalize()

🧐 예외) 첫번째 또는 두번째 argument 이후에 주요 argument가 아닌 경우에는 유창함이 떨어지는 것이 허용됩니다.

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

factory method의 시작은 make로 시작합니다.

struct List {
    func makeIterator() -> IteratorProtocol {
        Iterator(self)
    }
}

x.makeIterator()

initializer의 argument와 factory method 호출에는 경로로 시작하는 구절로 구성하지 마세요

//Good(👍)
///#1
struct Color {
    init(red: Int, green: Int, blue: Int) {}
    func makeWidget(gears: Int, spindles: Int) -> Widget{ Widget() }
}
let foreground = Color(red: 32, green: 64, blue: 128)
let newPart = factory.makeWidget(gears: 42, spindles: 14)

///#2
struct Link {
    init(target: Destination) {}
}
let ref = Link(target: destination)

///#3
struct RGBColor{
    init(_ cmykColor: CMYKColor) {}
}
let rgbColor = RGBColor(cmykColor)


//Bad(👎)
///#1
struct Color {
    init(havingRed red: Int, green: Int, and Blue: Int) {}
    func makeWidget(havingGearCount: Int, andSpindleCount: Int) -> Widget { Widget() }
}
let foreground = Color(havingRGBValuesRed: 32, green: 64, andBlue: 128)
let newPart = factory.makeWidget(havingGearCount: 42, andSpindleCount: 14)

///#2
struct Link {
    init(to target: Destination) {}
}
let ref = Link(to: destination)

부수효과(side-effect)를 기반해서 function 과 method의 네이밍을 하세요.

• side-effect가 없는 것은 명사로 읽혀야 함. e.g.) x.distance(to:y), i.successor()
• side-effect가 있는 것은 동사로 읽혀야 함 e.g.) print(x), x.sort(), x.append(y)
• mutating/nonmutating method의 이름을 일관성 있게 짓기.
  • operation이 동사로 설명되는 경우: mutating에는 동사의 명령형(sort(), append())을 사용, nonmutating에는 'ed', 'ing'를 접미사로 붙여서(sorted(), appending()) 사용함
• operation이 명사로 설명되는 경우: mutating에는 form접두사 붙여서 사용(formUnion, formSuccessor), nonmutating에는 명사 활용(union, successor)

nonmutating인 Boolean 메소드와 프로퍼티는 호출되는 객체에 대한 주장문처럼 읽혀야 한다

x.isEmpty , line1.intersects(line2)

어떤 것이 무엇인지를 설명하는 프로토콜은 명사로 읽혀야 합니다

Collection

능력을 설명하는 프로토콜은 able, ible, ing를 사용한 접미사로 네이밍해야 합니다

Equatable , ProgressReporting

protocol ProgressReporting{}

extension ProgressReporting{
    func reportProgress() {
    }
}

나머지 types, properties, variables, constants는 명사로 읽혀야 합니다

(3) Use Terminology Well

1. 일반적인 단어가 의미를 더 잘 전달한다면 잘 알려져 있지 않은 용어를 사용하지 마세요.
2. 전문 용어를 사용한다면 대중에게 인정받는 정의 를 사용하세요.
3. 약어(줄임말, abbreviations)을 피하세요
4. 관례를 따르세요.

참고

• 공식 문서: https://www.swift.org/documentation/api-design-guidelines/
• 번역본: https://cozzin.gitbook.io/swift-api-design-guidelines/naming/strive-for-fluent-usage