[Swift API Guidline] Naming

의역 오역 많을 겁니다~ 감안하고 보세요!

원문 : https://swift.org/documentation/api-design-guidelines/#naming

Naming

Promote Clear Usage

이름이 사용되는 경우 코드를 읽는 사람을 위해 모호함을 피하기 위한 모든 단어를 포함하라.

• 예를 들면, 콜렉션 내에 position으로 주어진 요소를 삭제하는 method를 고려하라.

• extension List {
    public mutating func remove(at position: Index) -> Element
  }
  employees.remove(at: x)

• 만약 우리가 method의 signature로 부터 at을 배제하는 경우, x를 사용하여 제거하기 위한 요소의 position으로 표시하는 것이 아니라 method가 x와 동일한 요소 검색하고 제거하는 것으로로 독자에게 암시할 수 있다. 

• employees.remove(x) // unclear: are we removing x?

불필요한 단어들을 생략하라. 이름의 모든 단어는 사용하는 장소에서 핵심적인 정보를 전달해야 한다.

• 명확한 의도 또는 분명한 의미를 위해 많은 단어들이 필요하다. 그러나 독자가 이미 점유하고 있는 정보로 불필요한 단어들은 생략해야한다. 특히, 단지 반복하는 형태의 정보의 단어들은 생략하라.

• public mutating func removeElement(_ member: Element) -> Element?
  
  allViews.removeElement(cancelButton)

• 이 경우 Element 단어는 호출 장소에서 두드러짐을 추가하지 않는다.

• 이 API는 아래의 겨우가 더 낫다.

• public mutating func remove(_ member: Element) -> Element?
  
  allViews.remove(cancelButton) // clearer

• 가끔, 모호성을 피하기 위해 반복하는 형태의 정보가 필요하다. 그러나 일반적으로 파라미터의 타입 보다 역할을 묘사하는 단어를 사용하는게 좋다.

변수, 파라미터 그리고 관련된 타입들은 그들의 타입 제약들 보다 그들의 역할들에 따라 명명하라.

• 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)
  }

• 만약 관련된 타입이 그 타입의 프로토콜 이름이 역할인 프로토콜 제약과 단단히 결합된 경우, 관련된 타입 이름에 'Type' 첨부에 의한 충돌을 피하라.

• protocol Sequence {
    associatedtype IteratorType : Iterator
  }

• 파라미터의 명확화로 약한 타입 정보를 위해 보상하라.

  • 특히 파라미터의 이름이 NSObject, Any, AnyObject, 또는 Int 또는 String 같은 기본적인 타입, 타입 정보와 사용 시점에서의 맥락은 의도가 완전히 전달되지 않는다.

  • 아래 예에서는, 선언은 명확하다, 그러나 사용 장소가 모호하다.

  • 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