命名って難しい - 命名で気をつけてること

はじめに

突然だが、世のエンジニアは変数名をいとも簡単につけているのだろうか？少なくとも私はいまだに変数名やメソッド名、カラム名などの命名に苦悩する日々を送っている(センスがない)。

つい先日、自分が不特定多数の別ユーザーに対してアクションを行った履歴データをDBから取得し、インスタンス変数に詰める際にその変数の命名で1時間ほど迷った。

頭の中「自分のアクションだからmyActionHistoryか？でも別ユーザーから自分に対してアクションした場合の変数も必要になった時を考慮して、actionByMeHistoryにすれば、actionBy◯◯Historyとできるから拡張性が少しは上がる？いや、actionToOtherUsersHistoryか？いやでも...」

こんなことをぐるぐる考えて約1時間。。。1時間もたってる！？このとき、命名の難しさを改めて感じた。
今回はこんな私でも命名する上で、気をつけていることを列挙してみようと思う。

dataやinfoは使わない

dataやinfoという単語はソース上で数多く見るが、これらは使わないようにしてる。
ユーザー情報を格納する変数として、userData,userInfoを例に挙げてみよう。、、、データ(data)なのは当たり前だし、情報(info)なのも当たり前なのでは？それならuserやusersのような命名にすべき。

Listはなるべく使わない

これは正直どちらでもいいと思うが、Listという単語をあまり変数名などで使わないようにしている。
例えば以下のコードでは、Userクラスでユーザー情報を管理していて、リストに詰めている。ただこの場合、何度もListが出てくる。userListと命名するなら、usersの方がスッキリしているし、複数のユーザー情報が格納されていることが伝わると思う。

sample1.kt

List<User> userList = new ArrayList<User>();

List<User> users = new ArrayList<User>();

ちなみに前述のものと合わせ技で、dataListなどという命名は絶対にしないようにすべき。なんのデータなのか、なんのリストかが何も伝わらない。読み手のことを考えた命名を意識すべき。

真偽値でFlagは使わない

例えば、その要素が有効なデータかどうかを管理する際の命名を、validFlagのような命名にはしない。この場合は、isValidにすべき。なぜならフラグにすると、複数解釈ができてしまうから。事実、フラグのonとoffが逆なのではないかと思う変数やカラムを数多くみてきた。
また、isInValidのような否定的な語句の変数名もよくない。これだと以下のような条件式の際に否定の否定で訳が分からなくなるから（私だけ？）。isValidの方がパッと見で伝わる。

sample2.kt

val isInValid = true
if (!isInValid) { // 無効ではない場合　＝　有効
}

val isValid = true
if (!isValid) { // 有効ではない場合
}

ちなみにisから始まる命名で真偽値を全てつけようとするとisExistのように意味は通るけど、英語的にダメなものもある。existは動詞なのでisとくっつけられない。存在するかどうかの場合はexistでもいいと思う。

is以外で始める場合は、動詞か助動詞を使えばいい。何かを所持しているかどうかはhas、含まれているかどうかはcontains、できるかどうかはcan（もしくはis〜able）。有効であるかどうかは、isValid。
よく使われるのはこの辺かと。

日付を取り扱うカラム名は過去形にする

変数名というよりはDBのカラム名に特化した話だが、日付情報をDBに登録する際には、過去形にすべきだと思う。理由としてはDBに情報が登録された段階で、処理が完了した時点の日付なので、過去形で作成であり、前置詞はatにする。例としてはcreated_atとかupdated_atなど。

masterは使わない

海外では、masterという単語は主人という意味が強くなるらしい。制御する側がmaster(主)、制御される側がslave(奴隷)という印象が残るようだ。また、blackListなども変数名としては向かない（あまり使わない命名だと思うが）。グローバルサービスなどでは、この辺りも気をつけるべき。
代替案としては、main/replicaなどだろう。Githubのデフォルトのメインレポジトリ名もmasterではなく、mainである。DBのテーブル名は、user_masterやitem_masterよりもusersやitemsなどの命名にすべき。

意味が伝わらないくらいなら、長くなってもいい

どれだけ長く考えても、いい命名が思いつかない場合がある。短くて分かりやすい命名がベストだと思うが、短くして意味が伝わらない変数名より長くてもこういうデータを格納してる、ということが分かる命名の方がいいはずだ。
最初に例に挙げた「自分が不特定多数の別ユーザーに対してアクションを行った履歴データ」を詰めた変数名に、私は最終的に「actionFromMeToOtherUsersHistory」と名付けた（なげー名前。。。）
正直もっと良い命名があっただろう、それでも頭を悩ませずに適当につけた命名よりは分かりやすいはず。

最後に

人から見たときに伝わりやすいこと、格納しているデータを分かりやすく表現できているかどうか、その命名が英文法としておかしいかどうか、命名においてはこの辺が重要だと思う。命名の分かりやすさは、コードの読みやすさやバグの防止につながる。たかだか命名などと考えず、熟考すべき。

そんな私もここ数年は命名について気をつけるようになったが、それ以前に私がなんとなくつけた変数やメソッド名、カラム名はどうなったのだろう。その後、あの変数たちがどうなったのかもう知る術はない。。。