Help us understand the problem. What is going on with this article?

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

More than 3 years have passed since last update.

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

関連

Why do not you register as a user and use Qiita more conveniently?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away