[iOS] 변수명, 어떻게 지을까? - API Design Guideline(1)

API Design Guideline의 원문과 번역본이 별도로 있지만,

단순히 읽기만 하면 잘 이해가 안 되더라도 그냥 넘어가거나 번역이 이상하면 눈에 들어오지 않아 나름대로 번역을 해봤다.

번역이라고 번역투이고 싶지 않아서 자연스럽게 써보고 싶었는데 뭔가 잘 안 되는 것이 아쉽긴하다. (번역이 이상하다는 말을 반성하게 됨.)

의역된 부분이 다소 있기에 불편하게 보는 사람들이 있을지도 모르겠다.

 

작성하고보니 전부 읽는 건 나중에 보게 될 나에게도 부담스러울 것 같아, 글을 3개로 나눴다.

Fundamentals ( 기본사항 )

사용 시점의 명확성이 가장 중요하다. 단순히 선언된 코드를 읽지 말고, 사용 사례를 생각하며 문맥상 명확한지 확인해라.
Clarity at the point of use is your most important goal. Entities such as methods and properties are declared only once but used repeatedly. Design APIs to make those uses clear and concise. When evaluating a design, reading a declaration is seldom sufficient; always examine a use case to make sure it looks clear in context.

Swift코드가 간결할 수는 있지만, Swift코드의 간결성은 상용구를 자연스럽게 줄이려는 특성과 강력한 Type system에 의해 생긴 Side-effect일뿐 간결함이 목적이 아니다.
Clarity is more important than brevity. Although Swift code can be compact, it is a non-goal to enable the smallest possible code with the fewest characters. Brevity in Swift code, where it occurs, is a side-effect of the strong type system and features that naturally reduce boilerplate.

모든 선언에 대해 Documentation comment를 작성해라. 문서 작성을 통해 얻은 인사이트는 디자인에 큰 영향을 미칠 수 있다.
Write a documentation comment for every declaration. Insights gained by writing documentation can have a profound impact on your design, so don’t put it off.

만약 간단한 용어로 API 기능을 설명하기 어렵다면, 잘못된 API를 설계했을지도 모른다.
If you are having trouble describing your API’s functionality in simple terms, you may have designed the wrong API.

Swift식 마크다운 방언을 사용해라.
Use Swift’s dialect of Markdown.

선언되는 Entity를 설명하는 요약부터 시작해라. API는 선언과 요약을 통해 온전히 이해할 수도 있다.
Begin with a summary that describes the entity being declared. Often, an API can be completely understood from its declaration and its summary.

/// Returns a "view" of `self` containing the same elements in
/// reverse order.
func reversed() -> ReverseCollection

요약에 Focus를 둬라. 많은 훌륭한 문서 comment들은 좋은 요약과 다를바 없다.
Focus on the summary; it’s the most important part. Many excellent documentation comments consist of nothing more than a great summary.

가능한 마침표로 끝나는 단일 문장으로 조각내라. 완전한 문장을 사용하지 마라. (한 문장에서 한 가지만 설명라는 뜻인듯??)
Use a single sentence fragment if possible, ending with a period. Do not use a complete sentence.

Function이나 Method가 수행하거나 반환하는 것을 설명하되, Null effects와 Void Returns는 생략해라.
Describe what a function or method does and what it returns, omitting null effects and Void returns:

하지만, 드물게 popFirst()처럼 세미콜론(;)으로 구분된, 여러 문장 조각으로 구성된 경우도 있으니 참고하자.
Note: in rare cases like popFirst above, the summary is formed of multiple sentence fragments separated by semicolons.

/// 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?

---

접근하는 게 무엇인지 설명해라.
Describe what a subscript accesses:

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

---

Initializer가 무엇을 생성하는지 설명해라.
Describe what an initializer creates:

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

 

---

 

모든 선언에 대해, 선언된 Entity가 무엇인지 설명해라
For all other declarations, describe what the declared entity is.

/// 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?
  ...

원한다면, 하나 이상의 단락과 글머리 기호를 계속 작성할 수 있다. 단락은 빈 줄로 구분하고 완전한 문장을 사용해라.
Optionally, continue with one or more paragraphs and bullet items. Paragraphs are separated by blank lines and use complete sentences

/// 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")

언제든지 적합하기만 하다면, 요약 외 점보를 추가하기 위한 symbol documentation markup 요소를 사용할 수 있다.
Use recognized symbol documentation markup elements to add information beyond the summary, whenever appropriate.

Symbol command syntax로 인식되는 글머리 기호 항목을 사용하고, 알아둬라.
Know and use recognized bullet items with symbol command syntax. Popular development tools such as Xcode give special treatment to bullet items that start with the following keywords:

Attention	Author	Authors	Bug
Complexity	Copyright	Date	Experiment
Important	Invariant	Note	Parameter
Parameters	Postcondition	Precondition	Remark
Requires	Returns	SeeAlso	Since
Throws	ToDo	Version	Warning