[번역] Swift API 설계 가이드라인: 요약

원문 :  http://cleanswifter.com/swift-api-design-guidelines/

Swift로 깨끗한 코드를 짜려 할 때, Swift API Design Guidelines은 매우 중요한 것 중 하나이다. 이것을 본 적이 있는가? 사실 나는 애플의 WWCD 비디오를 보기 전까지 이것을 본 적이 없었다. WWDC 영상을 기다리면서 내 직장 동료와 이것저것 이야기 했는데, 영상이 눈에 잘 안들어올 여지가 있었다. 내가 직접 작업하는 것 말고는 다른사람이 사용하기 위해 "프레임워크" 형태의 코드를 작성하진 않는 사람 중 한명으로서, 나에게 이 영상의 설명과 직접 연관되있지 않을것이라 생각했다.

Swift3은 명확하고 정교한 Swift 코드를 위해 고유의 특징을 만들어 담은 새 API 설계 가이드라인을 소개한다. 이 이야기는 Swift API 가이드라인 너머에 있는 철학을 탐구하고 Swift 표준 라이브러리, Cocoa, Cocoa Touch API를 통한 그 응용프로그림을 탐험할 것이다. 어떻게 이 API 변형이 여러분 Swift 코드에 영향을 줄 수 있는지 확인해보고, 어떻게 Swift3으로 부드럽게 변형할 수 있는지 배워보자. Swift3이 어떻게 Objective-C API를 불러오는지, 어떻게 기존의 Objective-C 라이브러리를 Swift 인터페이스로 만드는지 배워보자.

비디오를 보고 나서 Swift.org에서 실제 설계 가이드라인을 읽어 보았는데, 의미있었고 여러분도 한번 읽어보기를 추천한다.

Swift API 설계 가이드라인은 여러분의 코드에서 변수, 파라미터, 메소드의 네이밍의 "단어"를 어떻게 만들어낼 것인지에대한 설명의 메뉴얼이다. 이것은 여러분의 코드에서 단어들을 어떻게 잘 조합할 수 있는지 연관된 문서를 제공하면서 이야기한다. Swift API 설계 가이드라인과 친해질수록 커뮤니티의 코드와 일관성을 가지게 될 것이며, 애플이나 Swift팀의 프레임워크에서 만들어진 API이다(원문: the APIs that are being created within the frameworks right out of Apple and the Swift team). 이것은 윈/윈의 방법이다.

아래는 내가 뽑은 Swift API 설계 가이드라인의 중요 포인트이다.

"ed/ing" 규칙

WWDC 영상의 발표자는 이 규칙은 "ed/ing" 규칙이라고 말했다. Swift.org 문서에서는 strive-for-fluent-usage">String for Fluent Usage 섹션에서 그 사이드 이펙트에의한 함수와 메소드 이름으로서 소개되어있었다. 가이드라인에서는 "가변의 메소드가 종종 유사한 의미에서 불변 변형을 가지는데 이때는 그 자리에서 인스턴스를 갱신하는 것 보다는 새로운 값을 반환하는게 낫다"고 한다. ed/ing 규칙에 따라 불변 버전 뒤에 붙인인다. 아래 예시이다.

가변(Mutating)

x.sort()
x.append(y)

불변(Nonmutating)

z = x.sorted() 
z = x.appending(y)

필요없는 단어는 생략하기

Objective-C로부터 남아있는 나쁜 습관이 하나 있다면, 장황한 메소드 이름인데, 특히 반복적으로 사용되는 단어들이다. 예를들어 Objective-C의 NSMutableArray 클래스 문서를 열어 "Object"가 몇번 나오는지 한번 세어보자. 이런 메소드는 Objective-C Foundation API 전반에 걸쳐 나타난다.

- (void)addObject:(ObjectType)anObject; 
- (void)removeObject:(ObjectType)anObject;

NSMutableArray의 클래스 문서에 "Object"라는 단어가 몇번이나 들어갔는지 세어보아라. 결과적으로 내가 쓴 코드에도 그런식으로 하게 만든다.

반면 Swift에는 이런것이 없다. Swift 창시자들은 간결함과 명확성의 조화를 위해 힘쓰고 있는 중이다.

Swift 코드가 너무 생략되버릴 수 있는데, 작은 단어 갯수로 코드를 최소화시키는 것이 그 목표는 아니다. 너무 짧은 Swift 코드가 있는 곳에는 강타입 시스템의 부작용이다...

이 섹션의 마지막 부분과 연관이 있다. 강타입 시스템으로서 NSMutableArray API를 아래처럼 다시 설계해볼 수 있다.

func add(_ anObject: AnyObject) 
func remove(_ anObject: AnyObject)

메소드 이름에서 얼마나 "Object"라는 단어가 없어졌는지 보라. 이것은 가이드라인에서 말하는 "불필요한 단어 생략"의 결과물이다. 이렇게 하는 이유는 이 API 사용자들이 파라미터에 정의된 타입으로만 오브젝트를 메소드로 보내기 위해 Swift의 강타입 시스템에 의존할 수 있기 때문이다. 이것은 Swift API 디자인 가이드라인 안에서 얘기하는, 불필요한 단어 생략을 통해 더 명료한 코드를 만드는 하나의 예시일 뿐이다. 이제 이것을 알았다면 가이드라인을 읽으면서 그것들을 여러분의 API 설계에까지 적용시켜볼 수 있다.

또한 Swift API 설계 가이드라인에서 변수, 파라미터, 연관타입, 네이밍에 해당하는 규칙들과 약타입 정보에 대한 보장 부분을 확인해보아라. 여기에 자세한 예제가 있지는 않지만, 이 가이드라인에서는 어떻게 필요없는 단어를 생략하여 명료함을 달성할 수 있는지에대한 좋은 안내서를 제공한다. 단 명료함을 넘어 축약이 되지 않도록 조심하자. WWDC 발표자가 언급한 것처럼 API는 꽤 간결하기 때문에 API 문서가 자꾸 바뀌길 원하지는 않을 것이다.

문법적인 영어 구(Grammatical English Phrases)

메소드와 함수의 이름은 문법적인 영어의 구처럼 읽을 수 있어야 한다. 나는 이 부분을 굉장히 좋아하는데, 자바 프로그래머로서 암흑기로부터 나를 끄집어내준 기분이 든다. 이것은 Swift API 설계 가이드라인의 strive-for-fluent-usage">String for Fluent Usage 섹션에서 이야기하고있다. 메소드와 파라미터 이름이 옳바른지 확인해보려면 코드를 소리내서 읽어보면 된다. "이것이 영문법적으로 옳바른가? 회화식으로 말할 수 있는가?" 이 질문에 대답이 그렇다면 아마 좋은 API 일것이다. 그렇지 않으면 다시 한번 생각해보아라. 여기 문법적으로 이해하기 쉬운 Swift.org에서 말하는 좋은 API 설계의 예시이다.

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”

나쁜 설계는 소리내서 읽기 힘들다.

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

다른 멋진 것들

문서

내가 전문적으로 사용해본 프로그래밍 언어 중에 가이드라인이 이렇게나 잘 정의된 코드 문서는 본적이 없다. Swift API  설계 가이드라인의 fundamentals">Fundamentals 섹션 상단에 있다. Swift 코드를 위한 문서를 작성할 때 고려해야하는 짧고 친절한 요점을 제공한다. 또한 만들어 놓은 문서를 Xcode가 어떻게 보여줄지와 함께 어떻게 그것과 일관된 주석을 달 수 있는지도 알려준다.

컨벤션(약속)

컨벤션 섹션은 매우 마음에 든다. 빅오(Big-Oh) 문서를 만들때나, 변수, 메소드 이름을 정하는 것들로부터 모든 것을 분명하게 설명해주는 1회성 코드들이 여기에 있다.

요약

나는 여러분에게 Swift.org에있는 Swift API 설계 가이드라인을 확인하라고 강요할 순 없다. 그래도 오늘 한 것이 여러분이 Swift 코드를 더 좋게 만드는데에 직접 행동으로 옮겨볼 수 있는 방법중 하나라는 생각이 든다. 가이드라인은 간단하고 깔끔하며 이해하기 쉽도록 배려해 놓았다. 여러분의 코드에 일관성이 생기는 것 뿐만 아니라 커뮤니티 어디에서나 쓰일 수 있는 일관성도 갖추게 될것이다. 이것을 누가 바라지 않겠는가?

즐거운 클리닝하기 바란다.