xho95 (소중한꿈)'s Swift Life

API Design Guidelines (API 설계 지침)

Table of Contents (목차)

Fundamentals (기반)

Naming (이름짓기)

Promote Clear Usage (명확한 사용법 추구하기)

Strive for Fluent Usage (자연스러운 사용법이 되도록 노력하기)

Use Terminology Well (용어를 잘 사용하기)

  Term of Art (전문 기술 용어)   명사 (noun) - 특정한 분야나 특정한 직업 내에서 엄밀하고, 특수한 의미를 가지는 단어 또는 구절9
       

Conventions (협약)

General Conventions (일반적인 협약)

Parameters (매개 변수)

func move(from start: Point, to end: Point)

Argument Labels (인자 이름표)

func move(from start: Point, to end: Point)
x.move(from: x, to: y)

Special Instructions (특수한 지시 사항들)

참고 자료

  1. ‘문서화 주석 (documentation comment)’ 이란 ‘Xcode 편집기’ 에서 스위프트 코드의 선언을 ‘옵션-클릭’ 했을 때 나타나는 주석을 말합니다. 문서화 주석은 개발자가 직접 추가할 수 있으므로, ‘API 설계 지침’ 에서는 자신이 작성하고 있는 코드에도 ‘문서화 주석’ 을 추가하라고 조언하고 있습니다. 

  2. 여기서 ‘문장 구절 (sentence fragment)’ 을 사용하라는 것은 완전한 문장이 아니라, 하나의 구절 형태로 사용하라는 의미입니다. ‘API 설계 지침’ 에서는 ‘요약 (summary)’ 에는 ‘문장 구절’ 을 사용하고, 이어지는 ‘문단 설명’ 에서는 ‘완전한 문장’ 사용하라고 조언하고 있습니다. 

  3. 링크 자체는 바로 위의 링크와 같은 symbol documentation markup 문서로 연결됩니다. 

  4. ‘메소드 서명 (method signature)’ 은 메소드 이름과 매개 변수의 개수 및 타입, 그리고 순서 등으로 구성된 것으로, 메소드를 식별하기 위해 사용되는 것입니다. 보다 자세한 정보는 위키피디아의 Type signature 항목에 있는 Method signature 부분을 보도록 합니다. 

  5. ‘공장 메소드 (factory method)’ 는 ‘공장 메소드 패턴 (factory method pattern)’ 에서 사용하는 메소드로, 구체적으로 ‘고정된 타입 (concrete type)’ 을 지정하지 않은 채 객체를 생성할 수 있게 해줍니다. 이에 대한 더 자세한 정보는 위키피디아의 Factory method pattern 항목과 팩토리 메서드 패턴 항목을 보도록 합니다. 

  6. ‘기본 이름 (base name)’ 은 함수 또는 메소드에서 매개 변수와 괄호를 뺀 순수한 함수 자체의 이름인 것으로 추측됩니다. 

  7. 컴퓨터 용어에서의 ‘부작용 (side-effects)’ 은 무조건 나쁜 것이 아니라 ‘부수적인 효과’ 정도의 의미로 이해할 수 있습니다. 

  8. 원문 자체가 위키피디아의 participle 항목에 대한 링크로 되어 있습니다. 

  9. 이어지는 내용을 보면 알겠지만, 스위프트는 이런 ‘기술 용어 (term of art)’ 대신 일상 용어를 더 많이 사용할 것을 권장하고 있습니다. 스위프트 표준 라이브러리에 있는 클래스들을 봐도, ImageButton 처럼, 접두사 없이 일상 용어로 타입 이름을 정하는 것을 볼 수 있습니다. 

  10. ‘verticalPositionOnUnitCircleAtOriginOfEndOfRadiusWithAngle’ 이 말을 직역하면 ‘각도를 가진 반지름의 끝이 원점에 있는 단위 원 상에 있을 때의 수직 위치’ 정도로 옮길 수 있습니다. 

  11. 컴퓨터 용어로 ‘복잡도 (complexity)’ 라는 것은 알고리즘을 실행하는데 필요한 자원의 총량을 나타내는 말입니다. 보다 자세한 내용은 위키피디아의 Computational complexity 항목을 보도록 합니다. 

  12. 스위프트에서 ‘자유 함수 (free function)’ 는 어느 영역에도 소속되어 있지 않은 ‘멤버가 아닌 함수 (non-member function)’-즉 일종의 전역 함수-를 의미합니다. 보다 자세한 내용은 위키피디아의 Free function 항목을 보도록 합니다. 

  13. ‘낙타 모양 대소문자 (camel case)’ 는, 변수 이름을 지정할 때 모든 단어를 붙이고. 각 단어의 첫 글자를 대문자로 표기하면, 모양이 낙타 등처럼 생겼기 때문에 나온 말입니다. ‘낙타 모양 대소문자 (camel Case)’ 에 대한 보다 자세한 내용은 위키피디아의 Camel case낙타 대문자 항목을 보도록 합니다. 

  14. ‘두문자어 (Acronyms and Initialisms)’ 는 ‘ASCII’ 같이 단어의 앞머리 글자만 떼어 만든 줄임말을 의미합니다. 그리고 영어의 ‘Acronyms’ 와 ‘Initialisms’ 는 사실상 같은 단어입니다. 우리말의 초성체 도 사실상 두문자어라고 할 수 있습니다. 보다 자세한 내용은 위키피디아의 Acronym 항목과 두문자어 항목을 보도록 합니다. 

  15. ‘기본 설정 매개 변수 (default parameters)’ 를 사용하면 함수를 호출할 때 그와 연관된 인자를 생략할 수 있어서 코드가 간단해집니다. 스위프트의 print(_:separator:terminator:) 함수가 대표적인 예라고 할 수 있습니다. 

  16. 원문에서는 ‘단사 사상 (monomorphism)’ 이라는 말을 사용하고 있지만, 이를 사실 ‘단사 함수 (injective function)’ 의 의미로써 사용하고 있습니다. ‘단사 함수’ 는 ‘정의역 또는 소스 (source)’ 에 있는 서로 다른 원소를 ‘공역 또는 결과 (result)’ 에 있는 서로 다른 원소로 대응시키는 함수를 말합니다. 보다 자세한 내용은 위키피디아의 Monomorphism 항목 및 단사 사상 항목, 그리고 Injective function 항목 및 단사 함수 항목을 보도록 합니다.