[iOS] API Design Guidelines - Naming 애플식 네이밍

(의역주의)

Naming

---

명확한 사용

애매모호하게 작성하지 않기

Good

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

Bad

x를 없애는 것인지 x에서 없애는 것인지 모호함

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

 

불필요한 단어 생략

Good

public mutating func remove(_ member: Element) -> Element?

allViews.remove(cancelButton) // clearer

Bad

public mutating func removeElement(_ member: Element) -> Element?

allViews.removeElement(cancelButton)

 

변수, 파라미터, associated type의 이름은 역할을 포함

예) "인사"하는 string을 string이라고 이름짓지 말고 greeting이라고 하기

Good

var greeting = "Hello" protocol ViewController {
	associatedtype ContentView : View 
} 

class ProductionLine { 
	func restock(from supplier: WidgetFactory) 
}

Bad

var string = "Hello" protocol ViewController {
	associatedtype ViewType : View } 
    
class ProductionLine {
   	func restock(from widgetFactory: WidgetFactory)
}

associated type이 프로토콜 제약에 강하게 바인딩된 경우 프로토콜에 Protocol을 붙여서 충돌 피하기

protocol Sequence {
	associatedtype Iterator : IteratorProtocol
}

protocol IteratorProtocol { ... }

 

파라미터의 역할을 명확하게 하기 위해서 weak type 정보를 보정하기

weak type 파라미터 앞에 해당 역할을 설명하는 명사를 붙여서 명확하게 하기

Good

func addObserver(_ observer: NSObject, forKeyPath path: String) 

grid.addObserver(self, forKeyPath: graphics) // clear

Bad

func add(_ observer: NSObject, for keyPath: String) 

grid.add(self, for: graphics) // vague

 

 

유창한 사용을 위해 노력하기

메서드나 함수가 영어 문법적으로 맞게 작성하기

Good

x.insert(y, at: z) “x, insert y at z” 
x.subViews(havingColor: y) “x's subviews having color y” 
x.capitalizingNouns() “x, capitalizing nouns”

Bad

x.insert(y, position: z) 
x.subViews(color: y) 
x.nounCapitalize()

첫 번째나 두 번째 파라미터 이후에 의미에 영향을 주지 않는 건 그냥 작성해도 됨

AudioUnit.instantiate(
with: description,
options: [.inProcess], completionHandler: stopProgressBar)

 

factory 메서드는 make로 시작하기

x.makeIterator()

 

이니셜라이저나 factory 메서드호출 을 위한 첫 번째 인수는 기본 이름으로 시작하는 구절이 되면 안 됨

예) 유창한 언어 처럼 작성하면 "레드 그린 블루 RGB값을 가지고있는 컬러" 처럼 되는데 이렇게 작성하지 않고 컬러(레드: 그린: 블루:) 로 작성하기

Good

let foreground = Color(red: 32, green: 64, blue: 128) 
let newPart = factory.makeWidget(gears: 42, spindles: 14) 
let ref = Link(target: destination)

Bad

let foreground = Color(havingRGBValuesRed: 32, green: 64, andBlue: 128) 
let newPart = factory.makeWidget(havingGearCount: 42, andSpindleCount: 14) 
let ref = Link(to: destination)

 

함수나 메서드의 side-effects가 나타나도록 하기

x.distance(to: y)

side-effects가 있으면 명령형 동사 사용하기

print(x) 
x.sort() 
x.append(y)

 

Mutating/nonmutating 구분하기

/// Reverses `self` in-place. 
mutating func reverse() 

/// Returns a reversed copy of `self`. 
func reversed() -> Self 
...
x.reverse()
let y = x.reversed()

 

/// Strips all the newlines from `self` 
mutating func stripNewlines() 

/// Returns a copy of `self` with all the newlines stripped. 
func strippingNewlines() -> String
... 
s.stripNewlines()
let oneLine = t.strippingNewlines()

 

명사형일 경우 앞에 "form"을 붙여서 구분하기

//Nonmutating
x = y.union(z)
j = c.successor(i)

//mutating 
y.formUnion(z) 
c.formSuccessor(&i)

Bool을 사용하는 메서드나 프로퍼티는 nonmutating일 때, receiver에 대해 표현

x.isEmpty

 

무엇인지를 나타내는 프로토콜은 명사로 읽혀야함

Collection

 

기능을 설명하는 프로토콜은 접미사 able, ible, ing 사용하기

Equtable, ProgressReporting

 

타입, 프로퍼티, 변수, 상수를 명사로 읽혀야함

 

 

용어 잘 사용하기

어려운 용어(전문용어) 자제하기

예) "표피" 대신 "피부"라고 하기

줄임말, 약어 피하기

Good

BaseViewController

Bad

BVC

 

관용어(이미쓰고 있는 언어)사용하기

예) Array대신 List라고 사용하지 않기

 

https://swift.org/documentation/api-design-guidelines/