1. Swift : API Design Guidelines(진행중)

Ref. https://swift.org/documentation/api-design-guidelines/ 의 내용을 부분발췌하여 번역한 내용입니다.

1) 기본 원칙(Fundamentals)

* 사용 요점의 명확성(Clarity at the point of use) 

* 명확성은 간결성 보다 더 중요하다(Clarity is more important than brevity)

* 각각의 선언에 대하여 문서 주석을 작성하라(Write a documentation comment for every declaration)

 - If you are having trouble describing your API’s functionality in simple terms, you may have designed the wrong API.

   (만약 여러분의 API의 기능을 단순한 용어들로 묘사하는데 어려움을 가진다면, 여러분은 좋지 못한 API를 디자인했을지도 모릅니다.)

2) 이름짓기(Naming)

* 알아보기 쉬운 단어의 사용을 권장합니다. (Promote Clear Usage)

 - 단어의 모호함을 피하기 위해 요구되는 모든 단어들을 포함하세요. (Include all the words needed to avoid ambiguity)

 - 필요치 않은 단어는 생략하세요. (Omit needless words)

 - 변수, 파라미터 그리고 연관된 타입들까지 그들의 역할에 따라 이름을 지정하세요. (Name variables, parameters, and associated types according to their roles (...))

 -  취약한 타입의 정보에 대해서,파라미터들의 역할을 분명하게 하기 위해서 보완하세요 (Compensate for weak type information to clarify a parameter’s role)

3) 유창한 단어 사용을 위해 노력하라(Strive for Fluent Usage)

* Prefer method and function names that make use sites form grammatical English phrases. (해석이 잘 이해가 안되어, 예시를 봅시다!)

 - 아래는 단순히 코딩만 되어있는 반면에, 위의 코딩은 오른쪽에 영어로 분명히 그 역할이 나타나 있는 것이 보입니다. 문법적인 규칙을 명확히 하여 누구나 보기 쉽게 표현되어 있는 것이 인상적입니다.

* 팩토리 메서드의 이름은 "make" 를 붙여 시작하세요. (Begin names of factory methods with "make")

 - e.g. "x.makeIterator()"

 - Ref. 팩토리 메서드에 관하여 잘 정리한 블로그가 있으니 참고해보세요 

  (https://horajjan.blog.me/220804516206)

* The first argument to initializer and factory methods calls should not form a phrase starting with the base name.

 1. 문장보다 예시를 통해 조금 더 빠른 이해가 가능할 것 같습니다. 아래의 빨간 부분은 좋지 못한 예이고, 위의 초록 부분이 권장되는 부분입니다. 

 2. 매개 변수를 지정하는 부분에서 아래는 havingRGBValues 혹은 havingGearCount와 같은 매개변수명이 들어가면서 코드가 간결해 보이지 않습니다.

 3. 앞의 having이나 접속사 and 와 같은 경우는 생략해도 의미 전달에 크게 문제가 되지 않습니다.

* Name functions and methods according to their side-effects. (아직 개발의 깊이가 깊지 않아서 그런지 이 문장의 해석이 와닿지 않습니다.. 아시는 분 코멘트 주시면 감사드리겠습니다.)

* 불리언 타입의 메소드와 프로퍼티의 사용은