Swift API 설계 지침

* 계속 공부하며 수정될 문서입니다. 마지막 업데이트 3/8

 

Apple devloper 공식 가이드를 참고하며 공부했습니다.

https://swift.org/documentation/api-design-guidelines/

Swift.org

기초

• 사용 시점의 명확성
  엔터티는 한번 선언하지만 반복적으로 사용된다. 그러기에 용도가 명확하고 간결해야 합니다.
• 간결함 < 명확성
  최소한의 문자로 가능한 한 작은 코드를 사용하는것이 코딩의 목표는 아닙니다.
• 주석
  문서를 작성하며 얻은 통찰력은 디자인에 큰 영향을 미칠 수 있습니다.
  주석 입력을 게을리 하지 말자

---

API의 기능을 간단히 설명하지 못한다면, API를 잘못 설계했을 수 있다.

---

 

이름짓기

기본 규칙

Lower Camel Case : function, method, variable, constant

Upper Camel Case : type(class, struct, enum, extension...)

 

명확한 사용처를 알려야 한다

• 코드를 읽는 사람이 명확히 알기 위해 모든 단어를 포함하자.
  ex) employees.remove(at: bob)

• 불필요한 단어를 생략하자.
  ex) employees.removeElement → employees.remove

• 제약조건이 아닌 역할에 따라 이름을 지정하자.
  ex) var String = " bob " → var name = "bob"

• 빈약한 유형정보를 보충하자
  매개변수 유형이 사용 시점에서 상황이 입력정보와 의도를 전달하지 못 할 수도 있음.
  이때 추가 보충해주자.

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

 

---

계속 노력하자

• sites를 사용하여 문법적인 영어 구를 만들자.
  단, 첫번쨰나 두번째 인수가 호출의 의미의 중심이 아닐때 유창성이 저하되는것은 허용됨.

x.insert(y, position: z) → x.insert(y, at: z)
“x, insert y at z”

x.subViews(color: y) → x.subViews(havingColor: y)
“x's subviews having color y”

x.nounCapitalize() → x.capitalizingNouns()
“x, capitalizing nouns”

 

 

 

• 팩토리 메소드의 이름은 make로 시작한다.
  x.makeIterator();
• initialize 및 팩토리 메서드 호출에 대한 첫 번째 인수는
  기본 이름으로 시작하는 구문을 만들어서는 안된다.
• side effect에 따른 명명기능과 방법
   a. side effect가 없는것은 명사구로 읽는다.
   b. side effect를 가진 것은 필수 동사구문과 같이한다.
      ex)pront(x), x.sort(), x.append(y)
• 변이 / 변이되지 않는 메서드 쌍을 일관되게 이름을 지정한다.
• 연산이 동사에 의해 자연스럽게 설명이 된다면,
  변환 방법에 동사의 명령을 사용하고 ed 또는 ing 접미사를 적용해
  변이되지 않는 대응요소의 이름을 지정합니다.

동사의 과거분사(ed추가)를 사용해 변형되지 않는 변형의 이름을 지정하는것을 선호한다.
x.sort() → z = x.sorted()

 

동사는 목적어를 갖으므로, add 문법이 아닌 append를 사용할 때, ing를 추가하는것을 선호합니다.

x.append(y) → z = x.appending(y)

 

연산이 명사로 자연스럽게 셜명되는 경우, 비변이 방법에 명사를 사용하고

from 접두사를 사용해 변형에 대응하는 이름을 지정합니다.

Nonmutating x = y.union(z) j = c.successor(i)

mutation y = formUnion(z) c.fromSuccerssor(&i)

 

용어를 잘 사용하자

모호한 용어를 피하고, Term of Art^[각주:1]을 사용시 기존 의미를 고수하자. 비표준 약어의 사용을 피하고 선례를 참고하자.

 

---

규약

일반 규칙

• 계산됙 속성의 복잡성을 문서화합니다
• 자유 함보수보다 메서드와 속성을 선호합니다.
• 케이스에 명시된 규칙을 따르십시오.
• 메서드는 이름을 공유할 수 있습니다. 단, 동일한 기본 의미를 공유하거나 별개의 도메인에서 작동될때에 한합니다.

매개변수

• 문서를 제공할 매개변수 이름을 선택합니다. 매개변수 이름은 중요한 설명 역할을 합니다.
• 기본 매개 변수를 활용하세요. 일반적으로 사용되는 단일값이 있는 모든 매개변수가 기본값 후보입니다.
• 매개변수 목록 끝에 기본값이 있는 매개변수를 찾는것이 좋습니다.

인수레이블

• 레비을 인수를 유의미하게 구별할 수 없는 경우
• 첫번째 인수가 전치사 구의 일부를 구성할 때 인수 레이블을 지정합니다.
• 첫번째 인수가 문법적 구문의 일부를 형성하는 경우는 레이블을 생략
• 다른 모든 인수에 레이블을 지정합니다.

---

 

1. Term of Art : 명사로써 특정 분야 또는 직업 내에서 정확하고 특수한 의미를 갖는 단어 또는 구 [본문으로]