LoginSignup
48

More than 5 years have passed since last update.

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

Last updated at Posted at 2015-12-09

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の意味は、そのシグニチャと1文か2文の要約によって理解できるのが理想的です。

    /// 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を設計している場合があります。

関連

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
48