やったこと

• API デザインパターン 3章 名前付け 読了

学んだこと

ポイント

• APIにおける、名前付けの重要性
• 「良い」名前の条件
• コンテキストが名前に与える影響
• 名前に追加で情報を与える手段

学び

• 公開情報の名前付けは、プログラミングでの名前付けよりも、ずっと重要度が高い
• 名付けにおける表現力とシンプルさはトレードオフ
• コンテキストによって、名前が持つ意味は変わり得る
• 名前に単位を含めると、利用者に、より明確な意図を伝えることが出来る
  • sec や msecは定番
• 名前に加えて専用のデータ型を定義すると、利用者に、より明確な意図を伝えることが出来ること

気づき

公開しているAPIの名前を変更するのは、電話番号や住所、主要メールアドレスを変更するのと同じぐらい大変。

とても良い例え。

メモ

名前の重要性

公開しているAPIの名前は非常に重要。

• 利用者の利便性に直結
• 後から変更することが非常に困難

公開しているAPIの名前を変更するのは、電話番号や住所、主要メールアドレスを変更するのと同じぐらい大変。

「良い」名前の条件

表現力があること、シンプルであること、予測可能であること。

◇表現力があること

名前から、名前を付けたリソースが何なのか、読み手に明確に伝わること。
特に、文脈が変わると意味が変わるような名前は要注意。「アカウント」や「メッセージ」など。

◇シンプルであること

表現力を失うことなく、最低限の文字数（単語数？）で読み手に情報を伝えることが出来ること。

• 名前は、長いほど表現力が上がりやすいが、理解に時間がかかる（≒複雑）
• 言い換えると、シンプルさと表現力はトレードオフ
• シンプルかつ表現力のある名前を模索することになる

◇予測可能であること

APIを一つ利用すると、他のAPIの使い方が何となくわかる（≒予測できる）、そんな状態。
名付けルールや、名前が持つ役割が一貫していると、利用者は予測しやすい。

言語、文法、構文上の注意

名前付けには、自然言語を使用する。
言語はルールが緩く，曖昧なもの。
これは、高い汎用性をもたらすというメリットになり、理解を阻害する原因というデメリットにも成りえる。

◇言語

• APIの名前付けには、英語を用いることが標準
  • 言い換えると、APIの名付けに英語以外のを使用すると、様々な弊害が生まれる

◇文法

RESTfull でないAPIの場合、アクションの名前付けに多様な選択肢が生まれる。
関数の名付けでは、よく命令形（createBook()など）や直接法（IsNullOrEmpty()など）が使用される。
APIの場合、命令形や直接法でもそのまま使えるとは限らない。

APIの名前で前置詞が使用される場合、APIの設計に根本的問題が潜んでいる可能性を示唆している。

• 前置詞の使用を禁止しているわけではない
• API名に前置詞を見かけたら、「問題を書けていないか調査する価値がある」ことを示している

複数のリソースを返す場合、末尾に s や es を付与するべきか？
- person リソースの複数形は persons? それとも people? など
- -> 安易に、「複数リソースを返す時はリソース名に s を付けよう」という発想があまりよくないことがわかる

◇構文

表記法は、「キャメルケース」「スネークケース」「ケバブケース」など。
表記法の使用には一貫性があることが望ましい。
- 何の単位でどの表記法を使用するかは統一する
- 一貫性が重要であり、どの表記法を使うかはあまり重要ではない

プログラミング言語の予約語は、可能な限り使用を避ける。
- つまり、 string String intといったフィールド名は避ける

コンテキスト

名前は、名前が登場する文脈（コンテキスト）によって変化しうる。

• 言い換えると、名前は、コンテキストと密接に関係する
• より正確な意味を伝えるメリットを持つ一方で、誤解を招く可能性があるデメリットもある

この点を踏まえ、APIの名前を決める際は、APIが使われるコンテキストを念頭に置くこと。

データ型と単位

自明な名前（firstNameなど）もあれば、文脈や単位によって意味が異なってくる名前（sizeなど）もある。

「文脈や単位によって意味が異なってくる名前」に明確な意味を持たせるには、以下のアプローチが考えられる。

• 名前に単位を含める
• 専用のデータ型を定義する（言語次第）

---

扱うこと

• なぜ名前を気にする必要があるのか
• 良い名前を付けたときの影響
• 言語、文法、構文の決め方
• コンテキストが名前の意味に与える影響
• ケーススタディ : 名前付けが良くないとどうなるか？

まとめ

• 良い名前は、良いAPIと同様に、シンプルで表現力があり、予測可能
• 言語、文法、構文（およびその他の任意の選択）に関しては、多くの場合、何かを選んでそれを一貫して使用するのが正解
• 名前に前置詞を含めることは、APIにとってマイナスになることが多い
  • 前置詞を含むAPIは、根本的な設計上の問題を抱えていることを暗示している
• コンテキストは、より分かりやすい情報はを提供すると同時に、誤解を生む原因になりえることも忘れてはならない
  • 名前を選ぶときには、名前が使用されるコンテキストに注意を払うこと
• 型情報を活用して、名前には含まれない情報を伝える
  • 特に、専用のデータ型は効果的