| description |
|---|
기초 |
- 사용하는 쪽에서 명확하다고 느끼게 하는 것이 가장 중요한 목표입니다.
메서드, 프로퍼티 같은 요소들은 한번 선언하고 반복적으로 사용합니다. 그런 요소들을 명확하고 간결하게 사용할 수 있도록 API를 설계하세요. 설계를 평가할 때, 선언한 쪽만 보고 평가하는 경우는 거의 없습니다. 항상 유즈케이스를 바탕으로 평가하게 됩니다. 특정 문맥 속에서 명확해 보이는지 확인합니다. - 명확한 것이 간결한 것보다 중요합니다. Swift 코드를 압축적으로 표현할 수 있긴 하지만, 가장 짧은 코드를 작성하는게 목표는 아닙니다. 타입 시스템과 boilerplate 줄여주는 기능들 덕분에 자연스럽게 Swift 코드가 간결해진 것 입니다. (짧게 표현하는 것을 목표로 두지 말자)
- 모든 선언에 대해 문서 주석(documentation comment)을 작성하세요. 문서를 작성하면서 얻은 통찰은 당신의 설계에 큰 영향을 줄 수 있습니다.
- 역자 주) 저는 모든 선언에 주석으로 설명을 할 필요는 없다고 생각합니다. 하지만 외부로 공개하는 모듈의 경우 해당 API를 설명하는 주석이 필요합니다.
{% hint style="info" %} API를 간단히 설명하는게 어렵다면, API를 잘못 설계했을 지도 모릅니다. {% endhint %}
- Swift의 마크다운 용어를 사용하세요.
- 요약으로 주석을 시작하세요. API 선언과 요약만으로 완전히 이해될 때가 있습니다.
/// Returns a "view" of `self` containing the same elements in
/// reverse order.
func reversed() -> ReverseCollection- 필요한 경우, 문단이나 bullet items(- 으로 구분되는 문장)을 추가하세요. 문단은 빈줄로 구분하고 완전한 문장을 사용합니다.
/// Writes the textual representation of each ← Summary 요약
/// element of `items` to the standard output.
/// ← Blank line 빈줄
/// The textual representation for each item `x` ← Additional discussion
/// 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")