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