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

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

More than 3 years have passed since last update.

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

Naming - 命名

Promote Clear Usage - 分かりやすい使い方を促進しよう

  • Include all the words needed to avoid ambiguity for a person reading code where the name is used.


  • For example, consider a method that removes the element at a given position within a collection


    public mutating func removeAt(position: Index) -> Element
  • used as follows:



  • If we were to omit the word At from the method name, it could imply to the reader that the method searches for and removes an element equal to x, rather than using x to indicate the position of the element to remove.


    employees.remove(x) // xを削除するんですか?

  • Omit Needless Words. Every word in a name should convey salient information at the use site.


  • More words may be needed to clarify intent or disambiguate meaning, but those that are redundant with information the reader already possesses should be omitted. In particular, omit words that merely repeat type information:


    public mutating func removeElement(member: Element) -> Element?
  • In this case, the word Element adds nothing salient at the call site. This API would be better:


    public mutating func remove(member: Element) -> Element?
    allViews.remove(cancelButton) // 分かりやすい

  • Compensate For Weak Type Information as needed to clarify a parameter’s role.


  • Especially when a parameter type is NSObject, Any, AnyObject, or a fundamental type such Int or String, type information and context at the point of use may not fully convey intent. In this example, the declaration may be clear, but the use site is vague:


    func add(observer: NSObject, for keyPath: String)
    grid.add(self, for: graphics) // 曖昧

  • To restore clarity, precede each weakly-typed parameter with a noun describing its role:


    func addObserver(_ observer: NSObject, forKeyPath path: String)
    grid.addObserver(self, forKeyPath: graphics) // 分かりやすい

Be Grammatical - 文法的である

  • Uses of mutating methods should read as imperative verb phrases, e.g., x.reverse(), x.sort(), x.append(y).

    (例) x.reserve()x.sort()x.append(y)

  • Uses of non-mutating methods should read as noun phrases when possible, e.g. x.distanceTo(y), i.successor().

    (例) x.distanceTo(y), i.successor()

  • Imperative verbs are acceptable when there is no good alternative that reads as a noun phrase


    let firstAndLast = fullName.split() // 好ましい

  • When a mutating method is described by a verb, name its non-mutating counterpart according to the “ed/ing” rule, e.g. the non-mutating versions of x.sort() and x.append(y) are x.sorted() and x.appending(y).


    x.sort(y) の non-mutatingバージョンは、x.sorted(y)
    x.append(y) の non-mutatingバージョンは、x.appending(y)

  • Often, a mutating method will have a non-mutating variant returning the same, or a similar, type as the receiver.


    • Prefer to name the non-mutating variant using the verb’s past tense (usually appending “ed”):


      /// selfの位置を反転します
      mutating func reverse()  
      /// selfを反転したコピーを返します
      func reversed() -> Self 
      let y = x.reversed()

    • When adding “ed” is not grammatical because the verb has a direct object, name the non-mutating variant using the verb’s gerund form (usually appending “ing”):


      /// selfから全ての改行を取り除く
      mutating func stripNewlines()  
      /// selfから全ての改行を取り除いたコピーを返す
      func strippingNewlines() -> String 
      let oneLine = t.strippingNewlines()

  • Uses of non-mutating Boolean methods and properties should read as assertions about the receiver, e.g. x.isEmpty, line1.intersects(line2).


    (例) x.isEmpty, line1.intersects(line2) // xは空である. line1はline2と交差する.

  • Protocols that describe what something is should read as nouns (e.g. Collection). Protocols that describe a capability should be named using the suffixes able, ible, or ing (e.g. Equatable, ProgressReporting).

    自身の性質(注: 意訳)を記述するようなプロトコルは名詞として読まれるべきです。(例: Collection)
    機能(能力)を記述するプロトコルは、able, ible または ingをサフィックスにつけて命名されるべきです。(例: Equatable, ProgressReporting)

  • The names of other types, properties, variables, and constants should read as nouns.


Use Terminology Well - 専門用語を使いましょう



Why not register and get more from Qiita?
  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
No 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