TIL (Today I Learned)

1월 10일 (수)

🔥학습 내용

Swift API Design Guidelines

• 목차는 크게 "Fundamentals, Naming, Conventions, Special Instructions"로 이뤄져 있다.

1. Fundamentals

Clarity at the point of use is your most important goal.
// 음.. 사용의 포인트를 명확하게 하는 것은 중요한 목표이다.

Clarity is more important than brevity
// 명확성은 짧게(줄임)는 것보다 중요하다. 
// 무슨 의미인지 명확하지 않다면, 무분별하게 단축, 줄임은 지양해야한다.

Write a documentiation comment for every declaration.
// 문서 작성 해라.
Insights gained by writing documentation can have a profound impact on your design,
// 문서 작성에서 얻는 인사이트는 당신의 설계에 매우 깊은 곳에 내재할 수 있다.
so don't put it off
// 그래서 포기하지 마라.

2. Naming

1) Promote Clear Usage

• Include all te words needed to aviod ambiguity for a person reading code where the name is used
  // 이름을 사용하게 될 때, 사람이 읽을 수 있는 코드로 부터 모호함을 피하는 모든 단어들은 포함된다.
• Omit needless words. Every word in a name should convey salient information at the use site
  // 불필요한 단어는 넘어가자. 이름의 모든 단어들은 사용하는 곳에서 중요한 정보를 전달해야만 한다.

[올바르지 않은 예]
public mutating func removeElement(_ member: Element) -> Element?

allViews.removeElement(cancelButton)

[올바른 예]
public mutating func remove(_ member: Element) -> Element?

allViews.remove(cancelButton) // clearer

• Name variables, parameters, and associated types according to their roles, rather than their type constraints.
  // 타입을 종속되서 이름을 짓기 보다는 각각의 역할을 짓는 게 좋다.

[올바르지 않은 예]
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)
}

• Compensate for weak type information to clarify a parameter's role.
  // 명확하게 파라미터들의 역할을 명확하게 하기 위해서 타입 일부분의 정보를 보충해서 이름을 지을 수 있다.

[올바르지 않은 예]
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

2) Strive for Fluent Usage

3) Use Terminology Well

• Avoid obsecure terms
• Stick to the established meaning if you do use a term of art
• Avoid abbreviations(약자, 생략)
• Embrace Precednet.

#. 참고자료

1. Swift API Design Guidelines URL: "https://www.swift.org/documentation/api-design-guidelines/#fundamentals"