More than 5 years have passed since last update.

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

Last updated at 2015-12-25Posted at 2015-12-23

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:

次のように使用します
```
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と等しい要素を検索して削除するように、読み手に誤解させる可能性があります
```
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?
allViews.removeElement(cancelButton)
```
In this case, the word Element adds nothing salient at the call site. This API would be better:

この場合、Elementという単語は、呼び出し部分で何も意味のある情報を与えません。
このAPIであればこうした方が良いでしょう。
```
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の型情報である場合、呼び出し箇所での型情報とコンテキストがが完全に意図を伝えないかもしれません。
この例でいくと宣言は明瞭ですが、使用箇所で曖昧になります。
```
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).

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

名詞として良い単語がない場合は命令的な動詞でも良いでしょう。
```
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"を追加)を使って、名前を付けましょう:
```
/// 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"を付加します)
```
/// 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を翻訳してみた(Naming)

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

Naming - 命名

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

Be Grammatical - 文法的である

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

関連