Fundamentals (핵심 개념)
Clarity at the point of use is your most important goal. Entities such as methods and properties are declared only once but used repeatedly. Design APIs to make those uses clear and concise. When evaluating a design, reading a declaration is seldom sufficient; always examine a use case to make sure it looks clear in context.
API 설계의 가장 중요한 목적은 사용하는 시점에서의 명료함입니다. 메서드나 프로퍼티와 같은 개체는 한 번 선언해두면 반복적으로 사용합니다. API는 이러한 개체들을 명확하고 간결하게 사용할 수 있도록 설계해야합니다. API 설계를 제대로 하였는지 평가할 때는 코드의 선언부를 읽는 것만으로는 충분하지 않습니다. 항상 문맥에 알맞도록 명확하게 설계하였는지 실질적인 사용 예시를 통해 확인해보아야합니다.
Clarity is more important than brevity. Although Swift code can be compact, it is a non-goal to enable the smallest possible code with the fewest characters. Brevity in Swift code, where it occurs, is a side-effect of the strong type system and features that naturally reduce boilerplate.
Write a documentation comment for every declaration. Insights gained by writing documentation can have a profound impact on your design, so don’t put it off.
If you are having trouble describing your API’s functionality in simple terms, you may have designed the wrong API.
Use Swift’s dialect of Markdown.
Begin with a summary that describes the entity being declared. Often, an API can be completely understood from its declaration and its summary.
/// Returns a "view" of `self` containing the same elements in /// reverse order. func reversed() -> ReverseCollectionFocus on the summary; it’s the most important part. Many excellent documentation comments consist of nothing more than a great summary.
Use a single sentence fragment if possible, ending with a period. Do not use a complete sentence.
Describe what a function or method does and what it returns, omitting null effects and Void returns:
/// Inserts `newHead` at the beginning of `self`. mutating func prepend(_ newHead: Int) /// Returns a `List` containing `head` followed by the elements /// of `self`. func prepending(_ head: Element) -> List /// Removes and returns the first element of `self` if non-empty; /// returns `nil` otherwise. mutating func popFirst() -> Element?Note: in rare cases like popFirst above, the summary is formed of multiple sentence fragments separated by semicolons.
- Describe what a subscript accesses:
/// Accesses the `index`th element. subscript(index: Int) -> Element { get set } - Describe what an initializer creates:
/// Creates an instance containing `n` repetitions of `x`. init(count n: Int, repeatedElement x: Element) - For all other declarations, describe what the declared entity is.
/// A collection that supports equally efficient insertion/removal /// at any position. struct List { /// The element at the beginning of `self`, or `nil` if self is /// empty. var first: Element? ...
Optionally, continue with one or more paragraphs and bullet items. Paragraphs are separated by blank lines and use complete sentences.
/// 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")Use recognized symbol documentation markup elements to add information beyond the summary, whenever appropriate.
Know and use recognized bullet items with symbol command syntax. Popular development tools such as Xcode give special treatment to bullet items that start with the following keywords: