사용 지점에서의 명확성이 가장 중요한 목표입니다.
메서드와 속성과 같은 개체는 한 번만 선언되지만 반복해서 사용됩니다.
API를 사용이 명확하고 간결하게 만들도록 설계하세요.
설계를 평가할 때 선언만 읽는 것은 거의 충분하지 않습니다.
항상 사용 사례를 검토하여 컨텍스트(문맥)에서 명확해 보이는지 확인하세요.
명확성이 간결함보다 더 중요합니다.
스위프트 코드는 간결할 수 있지만, 가능한 가장 작은 코드를 가능하게 하는 것은 목표가 아닙니다.
스위프트 코드에서 간결함이 발생하면, 이는 강력한 타입 시스템과 보일러플레이트*(상용문)를 자연스럽게 줄이는 기능의 부작용입니다.
모든 선언에 대해 문서 주석을 작성하세요.
문서 작성을 통해 얻은 통찰력은 설계에 큰 영향을 미칠 수 있으므로 미루지 마세요.
<aside> ☝ API의 기능을 간단항 용어로 설명하는 데 어려움이 있다면 잘못된 API를 설계했을 수 있습니다.
</aside>
/// Return a "view" of 'self' containing the same elements in
/// reverse order.
/// 동일한 요소를 역순으로 포함하는 'self'의 "view"를 반환합니다.
func reversed() -> ReverseCollection
More detail
/// **Inserts '**newHead**'** at the beginning of `self`.
/// `self` 시작 부분에 'newHead'를 삽입합니다.
mutating func prepend(_ newHead: Int)
/// **Returns** a `List` containing `head` followed by the elements
/// of `self`.
/// `head`와 `self`요소를 포함하는 `List`를 **반환합니다.**
func prepending(_ head: Element) -> List
/// **Removes and returns** the first element of `self` if non-empty;
/// returns `nil` otherwise.
/// 비어 있지 않으면 `self`의 첫 번째 요소를 **제거하고 반환합니다**. 그렇지 않으면 `nil`을 반환합니다.
mutating func popFirst() -> Element?
<aside> 📖 NOTE : 자주 사용되지는 않지만, popFirst의 경우처럼 세미콜론을 사용해 여러 절로 이루어진 요약문을 작성할 수도 있습니다.
</aside>
/// **Accesses** the `index`th element.
/// `인덱스`번째 요소에 액세스(접근)합니다.
subscript(index: Int) -> Element { get set }
/// **Creates** an instance containing `n` repetitions of `x`.
/// `x`를 `n`번 반복하는 인스턴스를 만듭니다.
init(count n: Int, repeatedElement x: Element)
/// **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.
/// `self`의 첫 번째 요소, 또는 self가 비어있는 경우 `nil`입니다.
var first: Element?
...
경우에 따라, 여러 절과 글 머리 기호를 사용할 수 있습니다. 공백 줄로 절을 나누고 완전한 문장을 사용합니다.
요약문 외에 추가 정보를 제공할 때에는 많은 사람들이 이해할 수 있게 **symbol 문서 마크업 요소들을 사용하세요.**
**symbol 커맨드 구문을 익히고 활용하세요.** Xcode와 같은 개발 도구는 다음 키워드로 사작하는 글 머리 기호 (예 - Note)를 특별하게 취급합니다:
| Attention | Author | Authors | Bug |
|---|---|---|---|
| Complexity | Copyright | Date | Experiment |
| Important | Invariant | Note | Parameter |
| Requires | Returns | SeeAlso | Since |
| Throws | Todo | Version | Warning |
이름이 사용된 코드를 읽는 사람을 위해 모호성을 피하고자 필요한 모든 단어를 포함합니다.
예를 즐어, 컬렉션 내에 주어진 위치에 있는 요소를 제거하는 메서드를 고려합니다.
✅
extension List {
public mutating func remove(at position: Index) -> Element
}
employees.remove(at:x)
메소드 서명에서 at 단어를 생략한다면, 삭제하려는 요소의 위치를 나타내기 위해 x를 사용하는 것보다는 x와 같은 요소를 검색하고 제거한다고 독자에게 암시할 수 있습니다.
🚫
employees.remove(x) // 불분명: x를 제거하는가?