わかりやすい変数名・関数名

可読性を高めるための最重要ポイントは、「わかりやすい変数名・関数名」をつけることです。

わかりやすい変数名

以下のソースコードを見てみましょう。

<?php
$num1 = 100;
$num2 = 300;

$r = 0.08;

$t_num = ($num1 + $num2) * (1 + $r);

echo '合計金額は' . $t_num . '円です';

このソースコードは、最終行まで読んで初めて、$num1, $num2が商品の金額、$rが消費税率、$t_numが合計金額を表していることがわかります。

では、以下のソースコードではいかがでしょうか。

<?php
$apple_price = 100;
$banana_price = 300;

$tax_rate = 0.08;

$total_price = ($apple_price + $banana_price) * (1 + $tax_rate);

echo '合計金額は' . $total_price . '円です';

処理内容は全く同じですが、上から順に各商品の値段、税率、合計金額と問題なく把握しながら読み進められるようになりました。これが変数名の力です。

優れた変数の命名のコツ

優れた命名を行うコツとして

  • 長い名前は問題なし。具体的な名前をつけよう。
  • 省略は基本的に使わない。タイピング速度よりも読解速度を高めよう。
  • 単語の間違いはバグの原因になりやすい。自信がなければ検索で確かめよう。

といったものが挙げられます。

長い名前は問題なし。具体的な名前をつけよう。

特に理由もなく、長い変数名を避ける方がいらっしゃいますが、極端に長い変数名でない限りは、多少長くても具体的な変数名をつける方が望ましくなります。

例えば、$totalという変数名では「合計数量」か「合計金額」かがわかりにくくなる場合があります。この場合に$total_price, あるいは$total_amountなどの名前を利用するのが望ましくなります。2単語から3単語程度、文字数にして20文字程度であれば許容範囲と考えてよいでしょう。

省略は基本的に使わない。タイピング速度よりも読解速度を高めよう。

合計を表すtotalをtで略したり、率を表すrateをrで略したりすると、コーディングの最中は楽になりますが、後で読み返したときにとても読みづらくなります。繰り返しのインデックスに使われるi, jなど、いくつかの例外はありますが、基本的には省略を使わないようにしましょう。

単語の間違いはバグの原因になりやすい。自信がなければ検索で確かめよう。

単語の間違いは、「正しい単語で書かれた変数」と「間違った単語で書かれた変数」の混在に繋がりバグの原因になりやすくなります。しかも、複数箇所で間違った単語が使われている場合、どんどん間違った単語が増殖していくことにもつながりかねません。少しでも自信がなければgoogle検索などで正しい綴りを確認し、間違った単語に気づいたら即座に直すよう意識しましょう。

わかりやすい関数名

次のソースコードを確認しましょう。

<?php
function check_integer($string){
  return preg_match('/^([1-9][0-9]*|0)$/', $string) === 1;
}

上記の関数は、整数であるかどうかを判定する関数で、trueかfalseが返り値となります。

一見問題なさそうに見えますが、

  • 整数であるときにtrueが返るのか、整数でないときにtrueが返るのかが不明確
  • 整数であるかどうかをチェックしているように見えるが、実際には「正の整数」かどうかをチェックしている

といった問題点があります。

次のソースコードを確認して見ましょう。

<?php
function is_positive_integer($string){
  return preg_match('/^([1-9][0-9]*|0)$/', $string) === 1;
}

関数名を変えるだけで、

  • isから始まっているため、正の整数であればtrueが帰ってくることが明確($string is positive integer)
  • positiveがつくことにより、正の整数の判定であることが明確になる

といったメリットが生まれます。作成した関数（オブジェクト指向で制作を行う場合はメソッド）は多くの方が利用する可能性があります。少しでもわかりやすい関数名をつけることで、関数利用のミスを減らし、チームの生産性を高めることにつながります。

わかりやすい関数名をつけておくことで、同内容の関数があるかどうかを探しやすくなり、重複した関数の作成を防ぐことができるのも一つのメリットと言えるでしょう。

わかりやすい関数名の命名のコツ

わかりやすい関数名の命名のコツとして、以下のものが挙げられます。

  • is, validなど、使いやすい単語をストックしておく
  • 名前がつけにくい時は関数の大きさを見直すサイン
  • 処理を具体的に説明する名前にする

is, validなど、使いやすい単語をストックしておく

例えば、true、falseが返る関数では、isから始まる関数名にしておくと、「ある条件に当てはまるならばtrue」「そうでなければfalse」が返る関数であることが一目でわかるようになります。

また、文字列が一定のフォーマットに従っているかどうかなど、入力値が正しいかどうかを判定するような関数では「valid（正しい）」という意味の単語を関数名に使うとわかりやすくなります。（is_valid_emailなど）

テキストや参考書の関数名などを見たら、使いやすい単語がないか確認する癖をつけておくと、命名を行うときに役立ちます。意識しておきましょう。

名前がつけにくい時は関数の大きさを見直すサイン

例えば、

  • 商品一覧をDBから取得して
  • 金額を税込に修正し、
  • 説明内のhtmlタグをエスケープする

そんな関数があったとき、どのような命名を行えばよいでしょうか？

このように、複数の仕事を同一の関数で行なっている場合には、命名に困ってしまいがちです。

原因は、多くの役割を詰め込みすぎた関数の側にあります。 まずは

  • 商品一覧をDBから取得する関数 fetch_items
  • 金額を税込に変更する関数 include_tax
  • 説明内のhtmlタグをエスケープする → 出力時のエスケープにする。

というように、関数を分解してしまえば、命名は容易になります。

命名が難しい場合は、まずは

  • 関数が大きくなりすぎていないか？

をチェックするとよいでしょう。

処理を具体的に説明する名前にする

例えば、processという名前の関数を作成したとすると、この関数が何をする関数なのかがよくわからなくなってしまいます。名前だけで関数の概要を把握できるような名前をつけることが重要です。

process, execute, 名詞のみ, のようなわかりにくい関数名をさけ、できるだけ動詞と名詞を組み合わせた「何をどうするのか？」がわかりやすい名前をつけるようにしましょう。

results matching ""

    No results matching ""