はじめに

今日も元気に働きバチ！こんにちは。廣田です。
弊社ではコミュニケーションツールとしてslackを使用していますが、たまに見るヘルプセンターの文面がユニークで仕事中にフフっとしてしまいます。

さて先日、先達の方々にコードを見ていただける機会がありまして
いろんなダメ出しがあったのですが、変数やメソッドの命名について多く指摘をうけました。

そこで結構前に紹介してもらっておきながら未だ読んでいなかった名著The Art of Readable Codeを読んだので、
命名について書いている2章から、学んだことを抜粋して紹介していこうと思います。

Packing Information into Names

名前はちょっとしたコメントのようなものです。
十分なスペースが無くとも、良い名前を選ぶことにより多くの情報を伝えることができるのです。

明確な単語を選ぶ

例えば ”get” という単語はとても不明確です。例えば以下のようなメソッドがあるとします。

def GetPage(url):
……

この場合、このメソッドはどこからpageを取得するのでしょうか。

ローカルキャッシュでしょうか？　DB、インターネットからかもしれません。
もしインターネットからであれば、FetchPage()やDownloadPageといったほうがより具体的です。

同様によく使われる単語としてsizeがありますが、返り値が予測できるような、より具体的な命名を考えるべきです。
例えばツリー構造の高さを示すならTreeHeight、ノードの数ならNumNodes()、メモリのサイズならMemoryBytes()など。

よく使われる単語について以下のように置き替えることで、より具体的な表現ができるでしょう。

不明確な単語	より明確な代替語
send	deliver, dispatch, announce, distribute, route
find	search, extract, locate, recover
start	launch, create, begin, open
make	create, set up, build, generate, compose, add, new

tmpやretvalのような総称的な命名を避ける

“Tmp”や”retval”, “foo”などはよく使われる命名ですが、そのものの持つ値や目的を描写するような名前を選ぶべきです。
以下のようなコードを例に見ていきましょう。

function (v) {
  var retval = 0;
  for (var i = 0; i &lt; v.length; i ++ ) {
	retval += v[i] * v[i];
	}
  return Math.sqrt(retval);
}

変数retvalは“I am a returned value”という以上の情報を含んでいません。

より良い命名とは変数の目的やそのものの含む値を詳細に表すものです。

先述のコードでは変数の中身は”v”の２乗の累積でした。
なのでより良い命名は、”sum_squares”などでしょう。このような命名にすることで、バグも見付けやすくなります。

抽象的な名前よりも具体的な名前をつけるようにする

たとえばServerCanStart()という名前のメソッドがあるとします。
そして、このメソッドはサーバが規定の TCP/IPポートをListenできているかを検証するものだとします。

この場合、より具体的な名前はCanListenOnPort()などでしょう。
こちらのほうが、メソッドがなにをするものなのかを直接的に示しているからです。

抽象的な命名をした場合、チームに新しく加わったメンバーにとって、それが何であるのか、なぜ必要なのかということが分かりにくくなってしまいます。

名前に追加の情報を付け加える

読み手が変数について知っておかなければならない重要な情報がある場合、
名前に追加の単語を付け加えることは価値のあることです。

たとえば16進数の文字列を含んだ変数があるとします。

  string id; // Example: "af84ef845cd8"

この場合、hex_id という名前のほうがより良いでしょう。
読み手がidのフォーマットは16進数だとわかるからです。

	変数名	より良い命名
暗号化されていないパスワード	password	⇒　plaintext_password
UTF-8にエンコードされたhtmlバイト	html	⇒　html_utf8

名前の長さはどの程度にするべきか？

変数名は長すぎてはよくありません。
名前が長くなればなるほど、覚えづらくなり、スペースも消費してしまいます。

一方、１単語、あるいは１文字の名前というのも考え物です。

短い名前は短いスコープで

複数ブロックにまたがるような変数に対し1,2文字の暗号のような名前を使ってはいけません。
そのような短い名前は２，３行の短い範囲で使用される変数には良いでしょう。

頭文字や省略形の使用

例えば”BackEndManager”のかわりに”BEManager”のような省略形を使うことがあります。
これは混乱を生じさせるでしょうか？

もしその省略形が、プロジェクトに特有のものであるときは使用を避けるべきです。
そのプロジェクトに新しく参加した人たちにとって暗号のようにしか見えないからです。
さらに言うと、そのコードを書いた人にさえ、ずっと後に見たときに暗号のように見えるはずです。

省略形を使えるかどうかの判断基準は
新しいチームメイトが、その名前が何を意味しているか理解できるか？
この１点です。

さいごに

と、ざっくりとまとめてしまいましたが、
初めてコードを見た人が「何を保持している変数なのか」、「具体的に何をする関数なのか」ということがわかる命名をするのが重要ということで、今後の業務で気を付けていこうと思います。

また、この内容はかなり私の意訳が入っているのと、実際の本にはもっとたくさんの例やコードが書いてあるので、そちらを読むことをお勧めします。
あと挿絵が面白いです(笑)

日本語の本もamazonで見かけました。

3章以降も学ぶ内容が多いので、自分のような初学者はまず読んだほうが良い内容だと思いました。
では今回はこの辺で。

イメージ・マジック開発者ブログ

命名について：The Art of Readable Codeを読んで。