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

# 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

    例えば、コレクション内の指定した位置にある要素を削除するメソッドを考えてみます。

    ```swift
    public mutating func removeAt(position: Index) -> Element
    ```

* used as follows:

    次のように使用します

    ```swift
    employees.removeAt(x)
    ```

    ----

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

    もしメソッド名から`At`を省略した場合、`x`を要素を削除するためのインデックスとしてではなく、`x`と等しい要素を検索して削除するように、読み手に誤解させる可能性があります

    ```swift
    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:

    意図を明確にする、もしくは細かな意味の違いを明らかにするために、より多くの単語が必要になるかもしれません。
    しかし、読み手がすでに処理している冗長な情報は省略されるべきです。特に、単に型名を繰り返すような単語は省略しましょう。

    ```swift
    public mutating func removeElement(member: Element) -> Element?
    allViews.removeElement(cancelButton)
    ```

* In this case, the word **Element** adds nothing salient at the call site. This API would be better:

    この場合、`Element`という単語は、呼び出し部分で何も意味のある情報を与えません。
    このAPIであればこうした方が良いでしょう。

    ```swift
    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:

    特にパラメータの型情報が`NSObject`、`Any`、`AnyObject`、もしくは基本的な型の`Int`、`String`の型情報である場合、呼び出し箇所での型情報とコンテキストがが完全に意図を伝えないかもしれません。
    この例でいくと宣言は明瞭ですが、使用箇所で曖昧になります。

    ```swift
    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:**

    明瞭さを取り戻すために、型情報が少ないパラメータは、役割を記述する名詞の前に置きましょう。

    ```swift
    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)`.

    mutatingなメソッドを使う場合は、命令的な動詞として読ませるべきです。
    (例) `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()`.

    non-mutatingなメソッドを使う場合は、名詞として読ませるべきです。
    (例) `x.distanceTo(y)`, `i.successor()`

    ----

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

    名詞として良い単語がない場合は命令的な動詞でも良いでしょう。

    ```swift
    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)`.

    mutatingなメソッドが動詞で記述されている場合、対応するnon-mutatingなメソッドはed/ingルールで命名しましょう。

    ```
    (例)
    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.

    多くの場合、mutatingなメソッドは、同一もしくは同様の型を返すnon-mutatingなメソッドを持つものです。

    ----

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

        non-mutatingな変形には、動詞の過去形(通常は"ed"を追加)を使って、名前を付けましょう:

        ```swift
        /// selfの位置を反転します
        mutating func reverse()  
        /// selfを反転したコピーを返します
        func reversed() -> Self 
        ... 
        x.reverse()
        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”):

        "ed"を追加した場合に文法的ではない場合(動詞が直接目的語を持つ場合)は、non-mutatingな変形には動名詞形で命名しましょう。(普通は"ing"を付加します)
        
        ```swift
        /// selfから全ての改行を取り除く
        mutating func stripNewlines()  
        /// selfから全ての改行を取り除いたコピーを返す
        func strippingNewlines() -> String 
        ... 
        s.stripNewlines() 
        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)`.

    non-mutatingなBooleanのメソッドとプロパティは、レシーバーに関する表明として読まれるべきです。  
    
    (例) `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 - 専門用語を使いましょう

`翻訳途中なので後日追加予定です`

# 関連

* [Swift API Design Guidelinesを翻訳してみた(Fundamentals)](http://qiita.com/__moai/items/2322365d34983093025d#swift-api-design-guidelines%E3%82%92%E7%BF%BB%E8%A8%B3%E3%81%97%E3%81%A6%E3%81%BF%E3%81%9Ffundamentals)
* [Swift API Design Guidelinesを翻訳してみた(Conventions)](http://qiita.com/__moai/items/1cde0971c0f889a06439)