Apple API Guidelines - Naming

1. 사용 시점에서 명확성(Clarity)을 강조하라

스위프트에서 이름을 정할 때 가장 중요한 목표는, “코드를 사용하는 사람이 해당 API를 호출할 때 의도가 명확히 드러나는가?”입니다. 이를 위해 다음 원칙들을 적용합니다:

1. 함수(메서드) 이름은 호출부가 하나의 문장처럼 자연스럽게 읽히도록 설계한다.

   // 예: Array의 remove(at:) 메서드는
   // "remove at index"라는 문장 구조가 된다.
   array.remove(at: 3)

2. 프로퍼티, 상수, 변수 등은 “이것이 무엇을 나타내는지”를 정확히 표현해야 한다.

   // 예: 'title'이라는 프로퍼티는 책의 제목, 뷰의 타이틀 등
   // 맥락을 명확하게 드러낸다.
   var title: String

---

2. 통일성(Consistency) 있는 용어 사용

• 같은 맥락에서 같은 개념을 반복해서 사용할 때, 동일한 단어를 사용한다.
• 예를 들어, “fetch”와 “retrieve”를 뒤섞어 쓰기보다는, 한 프로젝트 내에서는 “fetch”로 일관되게 사용함으로써 읽는 이가 혼동하지 않도록 한다.

---

3. 문법적(Grammatical) 구조로 자연스럽게

Swift 함수(메서드) 이름은 동작(동사)로 시작해, 파라미터 레이블과 함께 문장 형태를 이루도록 설계하는 것을 권장합니다.

func move(from startIndex: Int, to endIndex: Int)

• 호출 시: move(from: 0, to: 5) → “move from 0 to 5”라는 자연어 문장처럼 읽힌다.

또한, 메서드의 동작에 따라 부수 효과(사이드 이펙트)가 있는지 명확히 드러내도록 이름을 짓는다:

• 값을 변경하거나 삭제하는 경우에는 명령형 동사 사용.
• 값을 단순히 조회하는 경우에는 명사나 명사구 형태(프로퍼티) 혹은 동사형 메서드라도 의도가 ‘읽기’에 있음을 표현.

---

4. 불필요한 단어는 제거(Omit Needless Words)

• 이름이 길어진다고 꼭 나쁜 것은 아니지만, 의미 없는 수식은 빼는 편이 낫다.
• 예: func dismissViewController(animated: Bool) → func dismiss(animated: Bool)처럼 “ViewController”를 중복 표기할 필요가 없다면 생략한다.
• 다만, 생략으로 인해 오해가 생길 여지가 있다면 명시적으로 쓰는 것을 권장한다.

---

5. Boolean 프로퍼티·메서드는 질문(Assertion) 형태로

불리언 타입을 반환하는 프로퍼티나 메서드는 “~인가?”를 표현하도록 명명한다.

// 좋은 예
var isEmpty: Bool
func contains(_ element: Element) -> Bool

// 나쁜 예 (의도가 즉시 드러나지 않음)
var empty: Bool
func hasElement(_ element: Element) -> Bool

• 예외적으로, “readable”, “available” 등 형용사 형태가 더 자연스러운 경우에는 is를 붙이지 않을 수 있다. (ex. isHidden vs. hidden)

---

6. 명사 vs. 동사 선택

6.1 프로퍼티(명사형)

• 상태나 속성, 값을 직접 나타내는 경우, 프로퍼티로 표현하고 명사 형태로 짓는다.

  var count: Int

• 계산 가능한 값이라도 부수 효과 없이 읽기 전용이라면 계산 프로퍼티로 취급한다.

  var isFull: Bool {
      // ...
  }

6.2 메서드(동사형)

• 행동(Behavior) 또는 부수 효과를 일으키는 동작이면 메서드로 정의하고 동사 형태로 짓는다.

  func incrementCount(by value: Int) {
      // count 값을 변경
  }

---

7. 약어(Acronyms) 처리

• 널리 알려진 약어(예: URL, ID, HTTP)는 스위프트의 Camel Case 규칙에 맞추어 쓰되, 가독성을 해치지 않도록 한다.

  var userID: String
  var urlRequest: URLRequest
  var httpResponseCode: Int

• 너무 긴 단어를 의미 없이 축약하지 말고, 모호성이 없다면 풀어쓰는 편이 낫다.

---

8. 타입(클래스, 구조체, 열거형, 프로토콜) 이름

• UpperCamelCase(Pascal Case)를 사용한다.

  class UserManager { ... }
  struct PersonInfo { ... }
  enum FetchResult { ... }
  protocol DataConvertible { ... }

• 클래스나 구조체는 주로 명사 형태, 프로토콜은 때로 형용사 형태(Configurable, Animatable)를 사용할 수 있다.
• 열거형 케이스는 lowerCamelCase로 작성한다.

  enum ConnectionState {
      case disconnected
      case connecting
      case connected
  }

---

9. 인자 레이블로 맥락을 부여

Swift 함수에서는 매개변수마다 외부 인자 레이블을 지정해, 호출 시점에서 코드가 자연스럽게 읽히도록 할 수 있다.

func addSubview(_ view: UIView, positioned: NSWindow.OrderingMode, relativeTo other: UIView?)

• 호출 시점: addSubview(view, positioned: .above, relativeTo: referenceView)

이처럼 인자 레이블을 통해 함수 본문이 아니라 호출부에서 맥락이 드러나도록 할 수 있으며, Apple은 이를 적극적으로 활용하라고 권장한다.

---

10. 요약: 좋은 이름이란?

• 의도가 선명해야 한다: "이 메서드가 무엇을 하는지, 이 프로퍼티가 무엇을 담는지"를 이름만 보고도 추측할 수 있어야 한다.
• 부수 효과가 있으면 동사형으로, 단순 조회나 상태 표현이면 명사형으로.
• 일관된 용어 사용: 똑같은 일을 “fetch”라 했다가 다른 곳에서 “retrieve”라 부르면 혼란이 커진다.
• 불필요한 수식은 제거하고, 모호함을 유발할 수 있는 부분은 친절하게 풀어서 명명한다.
• 인자 레이블을 잘 활용해 “함수 호출” 자체가 문장처럼 매끄럽게 읽히도록 디자인한다.

---

마무리

Swift API Design Guidelines의 Naming 파트는, 크게 보면 “사용 시점에서 가독성을 극대화” 하는 것을 목표로 합니다. 이름은 길거나 짧거나가 문제가 아니라, 불명확함과 혼동을 최소화하는 것이 핵심입니다.

• 함수, 메서드 → 동작을 잘 드러내는 동사형
• 프로퍼티, 변수 → 속성이나 값을 나타내는 명사형
• Boolean 타입 → “참/거짓”의 의미가 명확한 질문(조건) 형태
• 인자 레이블 → 호출부에서 문장처럼 자연스럽게 읽히도록

이러한 원칙들은 Swift가 제공하는 문법(옵셔널, 후행 클로저, 중첩 타입 등)을 최대한 활용함과 동시에, 의도를 분명히 전달하여 코드의 품질과 유지보수성을 높이려는 철학을 반영하고 있습니다.

---

참고

Swift.org - API Design Guidelines (Naming)