API Design Guidelines - Naming(명명법)

Naming(명명법)

Promote Clear Usage

1. 모호성을 피하기위해 모든 단어를 포함해라(Include all the words needed to avoid ambiguity)
2. 
3. • 위의 예시의 경우 remove의 parameter에서 at을 사용하지 않으면 명확하지 않다. x에서 제거하는 것인지, x를 제거하는 것인지 불분명하므로 명확히 표현해줘야한다.
   • 반례에서 x가 position이 아니고 삭제하는 값 자체일 경우 label을 뭐라고 하는게 좋을까? ... label 없이 parameter로 value: x 로 표현해도 괜찮을 것 같다.
4. 의미없는 단어를 생략하라(Omit needless words)
5. 
6. • 명확성을 위해 더 많은 단어가 사용되는 것은 좋지만, 너무 많은 단어와 정보는 생략되어야 한다. 위의 경우, Element는 특정한 것을 나타내지 않고, 반복되므로 아래처럼 생략해주는 편이 더 낫다.
   • 때때로 타입 정보를 반복하는 것은 모호성을 피하는데 필요할 수 있지만 일반적으로는 파라미터의 타입을 직접 명시하기보다는 역할로서 타입을 드러내는 것이 더 좋다.
7. 그 역할에 관련지어 이름을 명명한다(Name variables, parameters, and associated types according to their roles)
8. 
9. • string -> greeting, ViewType -> ContentView, widgetFactory -> supplier로 이름을 바꿔줘서 보다 명확하게 의미를 전달하게 되었다.
     • 연관된 타입이 그 타입의 프로토콜 제약을 강하게 받을 경우 프로토콜 이름에 Protocol을 붙여 충돌을 방지한다.
     • Protocol 이란?: 메소드, 프로퍼티 등을 위한 청사진(A protocol defines a blueprint of methods, properties, and other requirements that suit a particular task or piece of functionality.)
10. (Learn more! ARC) 파라미터의 역할을 명확히 하기 위해 약한 타입 정보는 보강할 필요가 있다(Compensate for weak type information)

Strive for Fluent Usage

)

1. 영어로 문맥이 자연스러운 네이밍을 하는 것이 좋다(Prefer method and function names that make use sites form grammatical English phrases)
2. 
3. • 위치를 나타내는 position으로 표현하는 것보다 전체적인 해석이 가능한 at을 선호한다.
   • parameter명으로 전치사를 사용하는 것은 메소드 선언부에서 어색하게 읽힐 수 있기 때문에 label로 활용하는 것이 더 좋다.
4. factory methods는 make로 시작한다(Begin names of factory methods with “make”, e.g. x.makeIterator())
5. (질문!)The first argument to initializer and factory methods calls should not form a phrase starting with the base name, e.g. x.makeWidget(cogCount: 47)
6. 
7. function과 method는 그 외부효과(출력값에 영향을 미치지 않는 작업)에 따라 네이밍을 한다.(Name functions and methods according to their side-effects)
8. 
9. • 반환값에 영향을 주는 부분이 없는 메소드의 경우 명사구로 표현한다(distance는 x에서 y로의 거리를 계산하여 반환하며 그 사이 side-effect가 존재하지 않을 가능성이 크다).
   • print, sort함수는 반환값에 영향이 없이 동작하므로 동사구로서 표현한다.

Use Terminology Well

• Term of Art: 특정분야에서 엄밀하고 특별히 정의되어있는 전문용어

1. 일반적인 용어로 설명이 가능할 때 전문용어 등, 비 일반적인 단어를 피해라(Avoid obscure terms
   • 의미를 분명히 전달하는, 더 많이 사용하는 단어를 사용해라. 예를 들어, epidermis(표피)라는 단어를 네이밍에 쓰지말고 skin이라는 더 대중화된 단어를 사용한다.
2. 전문가든 초보자든 누가봐도 정확한 이해가 가능하도록 단어의 정확한 기존 의미를 지키며 명명해라(Stick to the established meaning)
3. 
4. • 일반적인 용어가 아닌 기술적 용어를 사용할 때는 일반적 단어가 모호하고 명확하지 않을 때 뿐이다.
   • Dont' surprise an expert: 전문가를 놀라게 하지 마라(이미 익숙한 단어에 새로운 의미를 재창조하지 마라)!
   • Don't confuse a beginner: 초보자들을 혼란스럽게 하지 마라(새로 배우는 사람이 웹 서칭을 하기 쉬워야한다)
5. 축약어를 사용하지 마라!(Avoid abbreviations)
6. • abbreviations의 예: INFO(information), Jan.(January), Mon.(Monday), Prof.(Professor)
   • 축약어와 Acronym(앞글자를 딴 단어)은 다르다.
7. 이미 통용되는 용어라면 조금 덜 익숙하더라도 습득하여 사용할 필요가 있다(이해가 더 쉬운 단어가 있더라도 기존에 자주 사용되는 용어라면 사용해라)(Embrace precedent)
8. 
9. • 초보자들의 입장에서 List라는 말이 더 이해하기 쉽다고 하더라도 연속적인 데이터 구조는 Array라고 명명하는 것이 더 좋다. 많은 프로그래머들이 이미 Array라는 말을 알고, Array가 무엇인지 금방 배울 수 있다.
   • 널리 통용되는 수학용어, 예를 들어 sin 함수 같은 경우는 그 의미를 모두 풀어쓰는 것보다 sine이라는 단어를 사용하는 것이 더 좋다.

Keywords: side-effect, mutating(nonmutating), protocol

Reference:

• https://swift.org/documentation/api-design-guidelines/#fundamentals
• https://shark-sea.kr/m/entry/iOS-ARC-strong-weak-unowned