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.


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


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


  • If you are having trouble describing your API’s functionality in simple terms, you may have designed the wrong 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