OpenStreetMap のエディターや、Mapbox の製品開発を率いた著名なエンジニア Tom MacWright (@tmcw) さんが、Gists に書いたプログラミングにおけるネーミングに関するメモを翻訳しました。
ある程度のスキルの人には常識的な内容とも言えますが、こういうレイヤーの話はなかなか文書化されることが無いなと思ったので、もし皆さんのお役に立てれば幸いと思います。
一部ニュアンスがわかりにくいところもあったので、もしもっといい役があるよ～という方はぜひ編集リクエストをお願いします。
プログラミングの中におけるネーミングという作業はとても難しいものです。でも不可能ではありません。そこで、私がいつも守っているガイドラインをいくつか紹介しましょう。
曖昧な言葉（weasel words）を避ける
ウィキペディアの weasel words に関する記事 がすごい。この文脈ではこんな言葉を指しています。
- Data
- Process
- Run
- Do
- Setup
これらの言葉は通常、全く意味がありません。どの変数でもデータと呼ぶことができます。どのメソッドもプロセスと呼ばれるかもしれません。これらの単語は、情報を与えたり、区別したりするものではありません。これらの名前を含むほとんどのメソッドや変数は誤ったネーミングです。よく考えて、何が良いのか考えてみてください。
-
processDataのようなメソッドは、おそらく単にデータを処理しているだけではないでしょう。たぶんprocessCsvではないでしょうか？ - それは本当にそのCSVを「処理」しているだけなのでしょうか。数値であるべき文字列を強制的に処理（coercing）しているのかもしれません。たぶん
coerceCsvRows?
たぶんこのほうがいいですよね！
-
dataは、たぶん単なるデータではないですよね。たぶんそれはrecentPosts（最近の記事）のようなものでは？
パターンに忠実に従う
データの型を示す何らかのグループがあるとしましょう。たとえば Commentable （コメント可能）や Archivable （アーカイブ可能）などです。これらは正確にいうと形容詞です。これらに続く部分については、たとえやっかいなケースがあったとしてもパターンに従ってください。
多くの場合、ルールに例外があるよりも、やっかいなケースを受け入れるほうが良いでしょう。例えば XMLHttpRequest は、頭字語を保持しないキャメールケース（XmlHttpRequest) でも、保持するキャメルケース (XMLHTTPRequest) でもない名前です。ルールは一つに統一しましょう！
文字数をケチらないようにしましょう
不必要な略語は、一文字の変数名より微妙な形です。何かが document であるならば、doc ではなく document と呼びましょう。国際化のことを i18n と呼ぶように、特別な例でのみ用いいるようにしましょう。
同じものを同じであることがわかるように
rowsという変数を持っていて、それを行データを扱うメソッドに渡したい場合、そのメソッドのパラメータも同様に rows という名前にするべきです。同じ種類のデータやインスタンスに対して異なる名前を使う理由がない限り、異なる名前を使わずに同じ名前を使いましょう。
同様に、不要な変数の代入を行わないようにしましょう。let theData = input のような代入でわかりやすくなったり、なんらかの目的を果たすことはありません。inputの型や値が変更され、別の名前を付ける必要がある場合にのみ再代入してください。
社内プロジェクトに名前をつけない
原則として、あなたのインフラの名前にスターウォーズに出てくる惑星の名前やロシア語で青や鳥の種類を表す言葉を使用するのではなく、それが何をするのかがわかるように名前をつけてください。社内プロジェクトのための洒落たネーミングは、今ではちょっとした楽しみとなっていますが、その一方で、わかりにく名前であることによって、プロジェクトに新しいメンバーを迎える際の終わりのない煩わしさがあります。メールを送信するマイクロサービスであれば、mail-serviceと呼んで終わりにしましょう。
物事が変わったら、名前を変えよう。
ネーミングの趣旨は常に問題です。たとえば sendMail と呼ばれてメールを送信していたメソッドが、単にメールのフォーマットだけを行い、実際にメールを送信する別のメソッドに渡すようにリファクタリングされた等です。コードをリファクタリングするときは、メソッドの名前も変更しましょう。
同様に、コードを書いているときも、「それが何をするのか？」と「それが何を呼んでいるのか？」をよく見て、ネーミングの趣旨とそれらが同じであることを確認してください。メソッドが renderPage と呼ばれていても、実際にはページをレンダリングするためのデータ構造をセットアップしているだけなら、別の名前にしましょう。
ネーミングが強いと、名前に頼ってしまいます。メソッド名を見れば、それが何をしているのか推測できます。まともな名前を選ぶことは有益な時間となります。