はじめに
webサービスを構築していく中で必要な知識を備忘録として残しております。
今回は 命名 について深堀りしていきたいと思います。
記事を読むと何ができるようになるか？
結論、伝わりやすいコーディング が身に付き、エンジニアとしての価値が上がります。
変数名の命名 をしっかり意識できれば、第三者から それだけで 「良いコード」 と認識できてしまいます。
良いコードの定義はいろいろありますが、
ここでは 第三者がコードの意図を理解するまでの時間をいかに早くできるか とします。
理解するまでの時間を早くすることは、プログラムを書く上でかなり重要とされています。
前提として、他人のコードを読むのはかなりのストレスです。
なぜなら、自身の考えとは異なる状態が コードに反映されているからです。
ただ、エンジニアという職業は 他人のコードを読み解く作業は 完全必須なので
必然的に 読みにくい、意図が伝わりづらいコードは 抹殺すべき対象 となるのです。
命名には、これっていう正解はないのですが
伝わりやすくする考え方はあります。本記事では、その考え方の紹介をしていきます。
私は 約１０年間 現場でエンジニアとして開発をしてきましたが
若手 ～ ベテランまで幅広く、意識できていない人が多すぎました。
肌感覚ですが 意識できている割合は２～３割です。
伝わりやすい命名とは？
伝わりやすい命名とは
結論、目的に沿って命名 （目的ベース命名）されているものです。
では、早速 ECサイトを例に
１．住所
２．商品
３．金額
の変数名を考えてみてください。
以下のように考えた方が多いのではないでしょうか？
$address; // ① 住所
$goods; // ② 商品
$amount; // ③ 金額
微妙な違いはあれど、考え方として大体の人はこのような命名をするかと思います。
ただこれは 目的ベースの命名になっておりませんので 残念ながら 伝わりずらい命名 です。
もっと言えば、人によって解釈が異なってしまう危険性があるのです。
伝わりやすい命名の考え方
では、伝わりやすい命名はどのように考えていけばいいでしょうか。
ステップは２つあります。
- 目的を考える
- 命名をする
住所ってなんの住所？
商品ってなんの商品？
金額ってなんの金額？
最初から安易に命名を決めるのではなく、まずは目的から考えます。
住所を例にすると
ECサイトでは、会員住所や配送先住所、配送元住所 などが複数の住所候補が考えられます。
その中でどういう場面で使用するか、100人が100人同じものをイメージできるように解像度を上げて考えます。
森 → 木 → 枝
イメージとしては、木や枝くらいまで具体的に落とし込めると良いです。
なので、変数にすると以下のように命名することができます。
$member_address; // 会員住所
$shipping_address; // 配送先住所
$shipping_from_address; // 配送元住所
会員情報の更新する場面であれば member_address
商品を配送する際の住所であれば shipping_address
といったように、目的を掘り下げて命名していきます。
これはあくまで考え方なので、使用する単語はそれぞれですが
重要なのは、目的ベースの考え方です。
どのような場面で使用される変数なのかを明確にイメージ
解像度を上げてより具体的に より具体的に を意識して命名を考える
この２つだけ覚えれば、実装に対する考え方も変わるはずです。
この後は、世の中にはびこっている 悪い命名例をご紹介いたします。
悪い命名例
技術主体命名
命名がプログラミング由来（型など）になっているもの。
けっこうやりがちですが 意図が伝わらないためふさわしくない命名です。
しっかり目的を表現しましょう。
$array_list;
$int_value;
$db_value;
直訳命名
単純に言葉を直訳してしまうものです。
すでにECサイトを例に紹介しているものです。
これもけっこうやりがちですので、思考停止せず、目的を抑えましょう。
$amount; // 金額を直訳
$value; // 値を直訳
$status; // 状態を直訳
連番命名
いわずもがなですね。これもけっこう見てきました。
$value_01;
$value_02;
$value_03;
フラグ（～flag）命名
フラグ命名自体は悪くないのですが、真理値（boolean）を入れている場合は
true・falseの状態が分かりずらいため、非推奨です。
$address_save_flag = true;
$address_delete_flag = false;
ぱっと見、trueがどの状態でfalseがどの状態か判断つきづらいですよね。
前後の処理や、文脈を見ていけばわかるかもしれませんが、人によって解釈が違うので、危険な状態です。
この後、解決方法を紹介します。
伝わる命名の小技
boolean値（真偽値）の命名ポイント
先にも述べましたが、true・falseの状態が明確にわかる命名を付けることが重要です。
ポイントしては、状況に応じて 変数に以下接頭辞（プレフィックス）を付けることで真偽値を明確にします。
is（～か）
can（～できるか）
has（～があるか）
should（～する必要があるか）
// is（～か）： 会員住所を更新したかどうか
$is_member_address_saved = true; // 更新した
$is_member_address_saved = false; // 更新していない
// can（～できるか）： 会員住所を更新できるか
$can_member_address_save = true; // 更新できる
$can_member_address_save = false; // 更新できない
// has（～があるか）： 会員住所の更新許可があるか
$has_member_address_save_permission = true; // 更新許可がある
$has_member_address_save_permission = false; // 更新許可がない
// should（～する必要があるか）： 会員住所を更新する必要があるか
$should_member_address_save = true; // 更新する必要がある
$should_member_address_save = false; // 更新する必要がない
上記のように、状況に応じて 接頭辞を付ければ、true・falseが明確になり
認識の齟齬がなくなり伝わりやすい命名へと昇華することができます。
必要な情報はできるだけ詰め込む（省略しない）
理想形としては、可読性を保つために 長すぎず、短すぎずですが
伝わればどんなに長くても良いのですが
一番やってはいけないのは、意味もなく省略して短くするケースです。
例として、以下の項目があると仮定します。
省略するケース、しないケースで比較していきたいと思います。
/** 返却削除管理番号 **/
// 省略した場合
$ret_del_ctl_num
// 省略しない場合
$return_delete_controll_number
意味がわからない名前ですが（例に出して恐縮ですが・・）
可読性を高めるために単語をひとつひとつ省略してしまうと、何を指している変数かわかりませんし
解読するために余計に時間がかかってしまいます。
なので、ある程度長くてもいいので、省略せずに命名することが伝わりやすいポイントです。
単数・複数系を使い分ける
変数に格納される値が単数なのか、複数なのかで 命名を仕分けましょう。
どのような値が入るかコードを詳細に追わなくても推測することがしやすくなります。
$member // 単数
$members // 複数
$member_list // 複数
命名はいかに伝わりやすくしたほうが良いかと理解できたのではないでしょうか。
この考え方は、変数名に限らず、関数名やデータベースカラムなど、様々な場面で使用できます。
重要なのは、目的をしっかり抑える 場当たり的な命名にならず、しっかり目的を掘り下げて
思考停止せずしっかり考えていきましょう。
より伝わりやすいコードが書けますし、自身のエンジニアとしての価値が上がると思いますので皆さん是非意識してみてください。