Swifter {Swift Developer}

메뉴

[Swift 3] API Design Guidelines 정리

Swift.org – API Design Guideline 을 읽어보고 한글로 번역해 보았다. 이 가이드라인은 앱구현시 특히 화면측 소스코드를 신경쓰지 못하는 것들을 정리한 느낌이다. 참고로 원문은 소스코드 예제가 있고 이 번역내용에은 대부분 생략했기 때문에 원문을 보는 것이 이해하기는 더 쉬울 수 있다.

기본

  • 용도를 명확하게 : 용도를 명확하게 한다는 것은 가장 중요한 기본요소로 소스코드를 쓰는 것보다 읽는 경우가 더 많기 때문이다.
  • 명확함은 간결함보다 더 중요 : 짧게 소스코드를 작성하는 것을 추구하다보면 너무 가독성등을 해칠 수 있기 때문에 이는 좋지 않다.
  • 문서화 주석 작성하기 : 모든 정의는 문서화 주석으로 작성하자. (역자: 처리에 대한 설명 주석이 아닌 클래스, 메소드 필드정의등의 주석을 가리킴)
    • Markdown 스위프트 특수어 활용
    • 요약을 사용
      • 요약이 가장 중요
      • 마침표끝 간결한 문장으로 설명
      • 메소드의 수 및 결과(리턴값) 언급
      • subscript가 무엇에 접근하고 있는지 설명
      • 이니셜라이저가 생성하는 것에 대해 언급
      • 선언된 엔티티가 무엇인지를 언급
    • 필요할 경우 주석에 이어 한개의 빈줄을 사이에 두고 세부사항 작성

이름짓기

클래스  및 메소드, 변수등에 대한 이름 짓기에 대해

사용법이 명확하게 되도록 배려하기

  • 모호성을 제거하기 위해 충분한 설명을 포함하기
  • 반대로 중복 단어 생략
  • 변수, 인수, 관련형(Associated Type)의 형이 아닌 역할에 따라 이름 짓기
  • 형이 약한 정의는 그것을 보충설명을 추가하기
    • NSObject, Any, AnyObject등이 인수에 무엇을 전달할 것인가에 대한 애매한 팁을 포함한 이름을 정함

확실한 표현을 하기

  • 영문으로 흐르듯이 읽을 수 있는 메소드 이름을 짓는다(인수 레이블 포함)
  • 팩토리 메소드는 make로 시작하자
    • 예: x.makeIterator()
  • 이니셜라이저 팩토리 메소드는 첫 인수설명을 생략하자
    • 예: factory.makeWidget(havdingGearCount: 42) 대신 factory.makeWidget(gears: 42)
  • 함수 및 메소드의 이름을 지을 때 그 작용에 따라 사용하자.
    • 변경조작하는 메소드는 명사화하자.
      • x.distanceTo(x), i.successor()
    • 변경조작하는 방법은 명령형 동사로 하자
      • x.reverse(), x.sort(), x.append(y)
    • 동사표현을 자연스러운 것으로 변경조작하는 메소드와 동등한 수정 작업을 하는 메소드가 있는 경우 ed/ding를 같이 사용한다.
      • x.sort()/x.sorted(), x.append(y)/x.appending(y) (역자는 변경조작하는 메소드는 리턴값에서 새로운 객체로 리턴처리된다)
        • 동사에 직접 목적어가 있다면 ed는 부자연스러운 경우 ing를 붙인다.
      • x.isEmpty, line1.intersects(line2)
    • 명사 표현을 자연스러운 것으로 변경조작하는 메소드와 같은 수정 작업하지 않는 메소드가 있는 경우 변경이 없음 : 명사이고 변경이 있는 경우 form+명사로 만든다.
      • 변경없음: x = y.union(z), 변경할수있음: y.formUnion(z)
  • 변경조작하면 리턴값이 Bool 메소드속성은 수신받는 검증되는 이름으로 짓자
    • x.isEmpty, line1.intersects(line2)
  • 그것이 무엇인지를 보여주는 프로토콜을 명사화한다.
    • Collection
  • 무엇을 할 수 있는지를 나타내는 프로토콜 able/ible/ing로 끝아는 이름으로 짓자.
    • Equatable, ProgressReporting
  • 기타 속성, 변수, 정수명은 명사화한다.

용어를 기분좋게 활용하기

  • 잘 알려져 있지 않거나 이해하기 어려운 말은 피한다.
    • 예: skin에 알맞는 것은 epidermis등을 사용하지 않는다
  • 확립된 용례에 따른다
    • 용어를 사용하는 것은 일반적인 용어보다 의미가 명확해질 때만 사용하도록 제한한다.
  • 약어는 피한다. (사전에 없거나 일반적이지 않는것)
  • 관습에 따른다.
    • 인접한 데이터구조는 List보다 Array가 적합
    • sin(x)는 sine(x)라고 명명해서는 안됨

관례

일반적인 관례

  • O(1)은 아니지만 computed property에는 주문계산량등의 설명과 같이 한다.
    • 속성은 일반적으로 O(1)인 것이 일반적이기 때문에
  • 다음의 경우 제외하고 기본적으로 함수보다 메소드 속성이 알맞음
    • 명확하면 self이지미나 없으면 없음
    • min(x, y, z)
    • 특히 무엇에도 속하지 않는 것은 일반적인
    • print(x)
    • 함수로 일반적인
    • sin(x)
  • 대소문자 규칙 지키기
    • protocol: UpperCamelCase
    • 아닌 경우: lowerCamelCase
  • 용도등 같은 메소드는 같은 인수정의등을 바꾸는 것만으로 좋음 (오버로드)
    • 반대로 용도 및 의미가 다른 것은 다른 이름으로 하기
    • 리턴형만 다르도록 함

인수

인수 자체가 문서역할을 이름정하기

문서에서 인수명을 가리키는 경우에도 알기 쉬운 이름을 의식한다

기본 인수를 활용하기

주요 용도에 맞게 선택적으로 인수에 알맞은 기본값 인자를 두면 이용시 편리함

뒤쪽 인수로 갈수록 기본값과 같은 것이 되도록 인수 순서를 배열

인수 레이블

  • 인수구분에 의미가 적은 경우 레이블을 생략함
    • min(number1, number2)
  • 캐스트같은 이니셜라이저에서는 레이블 생략함
    • Int64(someUInt32)
  • 첫번째 인수가 전치사인 역할을 담당할 경우 레이블 사용
    • x.removeBoxes(havingLength: 12)
    • 여러개의 인수가 전치사적인 의미를 가지는 경우는 예외로 메소드명에 대한 설명이동
      • a.move(toX: b, y: c) 대신 a.moveTo(x: b, y: c)
  • 한편 첫번째 인수가 문법적인 문구를 담당하는 경우 레이블을 생략하고 메소드명에 대한 설명을 지정
    • x.addSubview(y)
    • 반대로 그런 경우가 없는 경우 레이블링 (view.dismiss(animated: false))
  • 기타 모든 인수에 알맞은 레이블링

특별한 경우의 지침

  • 폐쇄의 인수 및 튜플의 멤버 레이블링
  • Any, AnyObject 제약없이 제네릭의 경우 특히 조심

자세한 부분은 원문의 예제를 참고로 보기 바란다.

Facebook Comments

카테고리:   Swift 3.0

댓글

죄송하지만 댓글은 닫혀 있습니다.