[번역] API Design Guidelines 번역 (1/3)

원본, 출처 : https://www.swift.org/documentation/api-design-guidelines/ 

Swift.org

앞으로도 여러 번 두고두고 읽을 내용이기에 번역을 했다.

완벽한 번역본이 아니므로 수정사항 있으면 알려주세요 !

 

API = Application Programming Interface(애플리케이션 프로그램 인터페이스)의 줄임말

 

 

(기본원칙) Fundamentals

API = Application Programming Interface(애플리케이션 프로그램 인터페이스)의 줄임말

• 사용 시점의 명확하게 하는게 중요하다.
  • 메서드, 프로퍼티와 같은 요소(entity)들은 한 번만 선언되지만 반복적으로 사용됩니다 . 용도가 명확하고 간결하게 API를 설계하십시오. 설계를 평가할 때 선언된 것을 읽는것으로 충분치않고 항상 사용 사례를 바탕으로 평가되기 때문에 문맥(맥락)에서 명확해야해합니다.
• 명확한게 간결함보다 중요
  • 스위프트는 코드를 간결하게 할 수 있지만, 적은 문자들로 가장 작은 코드를 만드는게 목표는 아닙니다. 스위프트 코드의 간결함은 강한 타입 시스템의 부수작용(side-effect)일 뿐 명료함을 더 중요시 생각해야 함
• 모든 선언에 대한 문서 주석을 작성하십시오.
  • 통찰력을 얻을 수 있는 문서작성은 설계에 지대한 영향을 미칠 수 있으므로 미루지 마십시오.
  • API의 기능을 간단한 용어로 설명하지 못하면 API를 잘못 설계했을 수 있습니다.

> more detail

• swift는 마크다운 은어를 사용한다( dialect of Markdown )
• 선언할 내용의 요약으로 시작하라. 때론 API는 선언과 요약으로 완전히 이해할 수 있다.

///Returns a "view" of `self` containing the same elements 
///in reverse order.
// = 본인이 보이는것을 동일한것을 포함하며 역순으로 리턴합니다.
func reversed() -> ReverseCollection

> more detail

• 요약에 초점맞추기 - 정말 중요한 부분. 많은 훌륭한 문서 주석은 좋은 요약의 구성이다
• 가능하면 마침표로 끝나는 단일문장조각(single sentence fragment)를 사용한다. 완전한 문장을 사용하지 않는다. (fragment = 불완정한 문장. 주어가 빠지든 목적어가 빠지든 문장구조가 불완전한것)
• 함수나 메소드의 수행내용과 리턴하는 것(반환값)을 설명하고, null 효과와 void반환은 생략한다.

///Inserts `newHead` at the beginning of `self`.
mutating func prepend(_ newHead: Int)

///Returns a `List` containing `head` followed by the elements
/// of `self`.
func prepending(_ head: Element) -> List

///Removes and returns the first element of `self` if non-empty;
/// returns `nil` otherwise.
mutating func popFirst() -> Element?

주의 : 위에서 드물게 popFirst 같은경우 요약은 여러문장으로 되며 세미콜론(;)으로 구분된 여러 문장의 형태가 된다.

• Subscript 가 접근하는 것 설명하기

///Accesses the `index`th element.
subscript(index: Int) -> Element { get set }

• Initializer가 무엇을 생성하는지 설명하기 :

///Creates an instance containing `n` repetitions of `x`.
init(count n: Int, repeatedElement x: Element)

• 그 외 다른 모든 선언의 경우 선언된 요소(entity)가 무엇을 하는지 설명하기.

///A collection that supports equally efficient insertion/removal
/// at any position.
struct List {

  ///The element at the beginning of `self`, or `nil` if self is
  /// empty.
  var first: Element?
  ...

• 선택적으로, 하나 이상의 단락 및 글머리 기호를 연속적으로 사용합니다. 단락은 빈 줄로 구분되고 완전한 문장을 사용합니다.

/// Writes the textual representation of each    ← Summary
/// element of `items` to the standard output.
///                                              ← Blank line
/// The textual representation for each item `x` ← Additional discussion
/// is generated by the expression `String(x)`.
///
/// -Parameter separator: text to be printed    ⎫
///   between items.                             ⎟
/// -Parameter terminator: text to be printed   ⎬Parameters section
///   at the end.                                ⎟
///                                              ⎭
/// -Note: To print without a trailing          ⎫
///   newline, pass `terminator: ""`             ⎟
///                                              ⎬Symbol commands
/// -SeeAlso: `CustomDebugStringConvertible`,   ⎟
///   `CustomStringConvertible`, `debugPrint`.   ⎭
public func print(
  _ items: Any..., separator: String = " ", terminator: String = "\n")

> More detail

• 해당되는 경우 공인된 심볼 문서 마크업 요소(symbol documentation markup)를 사용해 요약 이외의 정보를 추가합니다.
• 공인된 글 머리 기호와 심볼 명령문법을 알고 사용한다 (symbol command syntax). Xcode와 같은 인기 개발 도구는 다음과 같은 키워드로 시작하는 글머리 기호 항목을 특별 취급합니다.

참고 ) https://www.swift.org/documentation/api-design-guidelines/ 에서 연결링크 이용

글머리기호	뜻	사용
Attention	주의	- attention:
Author	작성자	- author:
Authors	작성자들	- authors:
Bug	버그	- bug:
Complexity	복잡성	- complexity:
Copyright	저작권	- copyright:
Date	날짜	- date:
Experiment	실험	- experiment:
Important	중요	- important:
Invariant	불변	- invariant:
Note	주의	- note:
Parameter	매개변수	- parameter
Parameters	매개변수들	- parameters:
Postcondition	수행 후 조건	- postcondition:
Precondition	전제 조건	- precondition:
Remark	논평	- remark:
Requires	필수 사항들	- requires:
Returns	반환	- returns:
SeeAlso	참조	- seealso:
Since	기록	- since:
Throws	예외 던지기	- throws:
Todo	할일	- todo:
Version	버젼	- version:
Warning	경고	- warning: