기본 개념
- 사용 시점의 명확성
- 메소드, 프로퍼티 등의 개체를 명확하고 간결하게
- 평가는 문맥상 명확하게 이해되는지를 기준으로
- 간결성보다 중요한 명료성
- 선언에 대한 주석 작성
- 선언된 개체에 대한 설명 요약
- 한줄로, 완전한 문장이 아닌, 마침표로 끝맺음
- 어떤 일을 수행하고
- 어떤 것을 반환하고
- 어떤 것에 접근하고
- 이니셜라이저가 무엇을 생성하고
- 선언된 개체가 무엇이고
- 심볼 문서 마크업 참고
네이밍
- 필요한 단어 사용 : 모호성 방지
- 불필요한 단어 생략
- 엔티티의 역할에 맞는 이름 선택
- 역할이 Protocol이라면, Protocol을 포함
- 파라미터의 역할이 명확하게 나타나는 이름 선택
능숙한 사용을 위한 노력
- 문법상 영어 문구 형태 선호
- 팩토리메소드의 이름은 make로 시작
- 첫번째 인자와의 연속성은 불필요
- 사이드이펙트가 없는 것은 명사구
- 사이드이펙트가 있는 것은 동사구
- mutating 메소드는 동사의 명령어 수식
- nonmutating 메소드는 -ed/-ing과 같은 접미사를 사용(보통 -ed 사용)
- 직접적인 목적어로 인해 -ed의 사용이 어려우면, -ing 사용
- 명사에 의해 연산 설명이 가능하다면
- mutating은 form 접두사를 사용
- nonmutating은 명사 그대로 사용
- Boolean 메소드와 속성 사용은 nonmutating일 때, 수신자의 주장으로 이해
- 무엇인지를 설명하는 프로토콜은 명사로
- 기능을 설명하는 프로토콜은 -able/-ible/-ing와 같은 접미사 사용
- 타입, 속성, 변수, 상수는 명사
전문 용어의 적절한 사용
- 굳이 필요치 않은 어려운 용어 사용 금지
- 전문 용어를 사용한다면, 기존 의미에 충실하게
- 약어는 비추천
- 넓게 사용되는 선례 용어 선호
규칙
- free 함수보다는 메소드와 프로퍼티 선호
- 명백한 self가 없거나, 함수가 generic하거나 등등
- case convention을 따르자
- 두문자어는 모두 대문자이거나, 소문자이거나로 일관되게(IAP, ASCII, …)
- 다른 약어는 일반적인 단어로 취급
- 반환타입에 오버로딩을 피하자
매개변수
- 문서(요약주석)을 쉽게 읽을 수 있도록 매개변수 이름 설정
- 일반적인 사용을 단순화할 때, 공통적으로 사용되는 값이 하나라면 기본값을 명시해 가독성 향상
- foo(bar: nil)과 foo()은 동의어가 아님
인자 레이블
- 인자가 유용하게 구별될 수 없을 때에는 모든 레이블 생략
- 인자에 전치사가 포함되는 경우, 명확한 추상화를 위해 인자가 아닌 이름에 전치사 사용
- 구문은 올바른 의미를 전달하는 것이 가장 중요함
특별 지침
참고
https://minsone.github.io/swift-internals/api-design-guidelines/?utm_source=soojinro&utm_medium=referral
