Swift API Design Guidelinesを翻訳してみた(Fundamentals)

Fundamentals - 基本

• Clarity at the point of use is your most important goal. Code is read far more than it is written.

  使うときの明瞭さは、最も重要な目標です。
  コードは書くことよりも読まれることの方が遥かに多いです。

  ---

• 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.

  明瞭さは簡潔さよりも重要です。Swiftではコードをコンパクトにすることもできますが、可能な限り短いコードで動作させるというのは目的ではありません。Swiftにおけるコードの簡潔さは、強力な型システムと、ボイラープレートコードが少なくなるという特徴の副産物として生まれます。

  ---

• Write a Documentation Comment for every method or property in Swift’s dialect of Markdown. Ideally, the API’s meaning can be understood from its signature and its one- or two-sentence summary:

  全てのメソッドやプロパティについてドキュメンテーションコメントをSwift用のMarkdownで書きましょう。APIの意味は、そのシグニチャと１文か２文の要約によって理解できるのが理想的です。

  /// Returns the first index where `element` appears in `self`, 
  /// or `nil` if `element` is not found. 
  /// 
  /// - Complexity: O(`self.count`). 
  public func indexOf(element: Generator.Element) -> Index? {
  

  ---

• Insights gained by writing documentation can have such a profound impact on your API’s design that it’s a good idea to do it early on.

  ドキュメントを書くことを早い段階で行うのは良いアイデアです。ドキュメントを書くことによって得られる深い理解は、APIの設計にとても大きな影響を与える可能性があります。

  ---

• If you are having trouble describing your API’s functionality in simple terms, you may have designed the wrong API.

  簡単な言葉でAPIの機能を表現することが困難な場合は、間違ったAPIを設計している場合があります。

関連

• Swift API Design Guidelinesを翻訳してみた(Naming)
• Swift API Design Guidelinesを翻訳してみた(Conventions)