この記事で分かること

・可読性の高いコードでプログラミングをする方法とそのメリット

先日アサインされたプロジェクトが終了し、自身のコードを振り返った際に、他の人のコードと比べて読み辛いと感じました。
これは改善しなくてはならないと思い、可読性の高いコードについて学び、それを自分なりにまとめたものをこのブログで紹介しようと思います。

目次

・可読性の高いコードとは?
  ・変数名、関数名の定義
  ・深いネストをやめる
  ・適切なコメントの使用
  ・マジックナンバーの使用を控える
・まとめ

可読性の高いコードとは?

人によって意見が違うと思われるため、ここでは私の考える可読性の高いコードについてお話させて頂きます。
まず、私が思う可読性の高いコードとは、修正がしやすく、必要以上に前後を追って読む必要がないコードであると思います。
では、可読性の高いコードの必要性とは何か。
業務上、自分で打ち込んだコードを読むのは自分だけではない事が殆どだと思います。
修正や、レビューやテストの作成、仕様変更や機能追加、ソースコードの流用時等様々な場面で、ソースコードを読むといった行動が関わってきます。
その際に可読性の低い、すなわち読み辛いソースコードで記載されていた場合

  • 影響範囲の調査や処理仕様の把握に時間が掛かる。
  • バグが発生しやすくなる。
  • バグの原因を特定するのに時間が掛かる。

等々、多数のデメリットが存在してしまいます。
可読性の高いコードを書く事でデメリットを抑制できると思います。

それでは、簡易的ではありますが、可読性の高いコードにする為にはどのように書けば良いか、PHPをサンプルコードに私なりに考えてみたいと思います。

・変数名、関数名の定義

まずは、以下のコードを見てみましょう。

$a = 10000;
$b = a($a);

上記コードのみを読んだだけでは何が書かれているか、何を行っているかがわかりません。
こちらをわかりやすく修正した場合が以下になります。

$user_id = 10000;
$user_name = getUserName($user_id);

こちらのコードでは10000という数字がユーザーID、関数ではユーザーIDを使いユーザー名を取得し、変数に代入している事がわかります。
ここで大事なことは、変数名や関数名等をわかりやすく書くこと、命名規則を統一することです。
その変数が何を表しているのか? この関数は何をしているのか? 等をわかりやすく書くことにより、前後を追って確認する手間が省けますし、些細なミスも減少するはずです。
命名についてはボリュームも大きい為、別の記事で紹介出来ればと思います。

・深いネストをやめる

ネストとは、入れ子の事です。
if文の中にif文等、条件分岐やループ内にまた別の条件分岐やループを入れる事を言います。
ifの中にif、その中にまたif、その中にfor …等といった深いネストは、やむを得ない場合もあるかとは思いますが、書き方を工夫する事で解消できる事も多いと思われます。できる限り控える事で、可読性の向上に繋がるはずです。
こちらも例を挙げてみていきましょう。
以下の商品Noを引数として、値段を取得し返却する関数には

  • 商品Noが1000以下のものは100円とする。
  • DBからの取得に失敗した場合エラーを返却する。
  • 値段が1500円以上のものは手数料100円がかかる。

という条件があります。

function example($item_no){
    $result = "error";
    $fee = 100;
    //条件①:商品Noが1000以下のものは100円とする。
    if($item_no <= 1000){
        $result = 100;
    }else{
    //金額をDBから取得
    //詳細は省略するがSearchItemPriceは$item_noをキーに
    //DBから金額を取得するメソッド
//【引数】$item_no:商品No
   //【戻り値】正常:金額 異常:false
$item_price = SearchItemPrice($item_no);
$result = $item_price; //条件②:DBからの取得に失敗した場合エラーを返却する。 if($item_price !== false){ //条件③値段が1500円以上のものは手数料100円がかかる。 if($item_price >= 1500){ $result = $item_price + $fee; } } } return $result; }

上記がネストを使用した際のコードとなります。
$item_noが1000以下ではなかった場合の処理が、追いにくいはずです。
こちらを修正したものが以下になります。

function example($item_no){
    $result = 100;
    $fee = 100;
    //条件①:商品Noが1000以下のものは100円とする。
    if($item_no <= 1000){
        return $result;
    }
  //金額をDBから取得
  //詳細は省略するがSearchItemPriceは$item_noをキーに
  //DBから金額を取得するメソッド
  //【引数】$item_no:商品No
  //【戻り値】正常:金額 異常:false $item_price = SearchItemPrice($item_no);
$result = $item_price; //条件②:DBからの取得に失敗した場合エラーを返却する。 if($item_price === false){ $result = "error";
//条件③値段が1500円以上のものは手数料100円がかかる。 }elseif($item_price >=1500){ $result = $item_price + $fee; } return $result; }

修正後のコードでは、$item_noが1000以下でなかった場合の処理も簡単に追うことができます。
コードの長さが長くなるにつれて、深いネストがある程可読性も低下していきます。そのため、できる限り深いネストの使用を控えましょう。

・適切なコメントの使用

コードにコメントを記入することはよくあると思います。コメントについては、業界でも意見がかなり分かれているようです。
私は、コメントはできる限り無い方が良い、と考えます。
理由としては下記があります。

①コメント自体にも保守作業が発生する事

②コメントを読む事で完結する場合、具体的な中身を見ずに理解することができてしまう事

③コメントの内容とソースコードの処理について差異が生まれる可能性がある事

②、③に関しては、意識をすれば回避できる事ではありますが、余分に作業が発生する事も考えられ、①については回避する事は難しいと思います。
しかしコメントがあることにより、このコードは何故このようにしているのか等、製作者の意図がわかりやすい事もまた事実ではありますので、必要最低限でコメントは記載が必要です。

・マジックナンバーの使用を控える

プログラミングをする上で、数字を使う事が多いと思います。もちろんそれは意味のある数字のはずです。
マジックナンバーとは、そのような意味のある数字ではあるがプログラム内に直書きされているため、何の数字なのか傍目にみてわからないような数字の事を言います。
以下、例を挙げてみましょう。

$total_price = $item_price * 1.08;

この、1.08という数字がマジックナンバーとなります。
こちらは簡単な例の為、1.08の部分で消費税の計算を行っているという想像がつく方も多いと思われます。
上記例ですと、以下のようにすることによりマジックナンバーの使用を回避できます。

$tax = 1.08;
$total_price = $item_price * $tax;

修正後の例では、1.08という数字を変数に入れることによりマジックナンバー化を回避しています。
この書き方であれば、1.08が消費税の計算の為に使われるものとすぐにわかりますね。
また、このような場合であれば、定数として定義してしまうのも手であると思います。
消費税率が変更された際に何処の数値を変更すればいいかが一目瞭然であったり、一括で変更できたりと利点が多いです。

まとめ

コードの可読性を高める事でバグを減らすだけではなく、工数削減や流用のしやすさにもつながり、様々な側面で大きなメリットが得られる事がわかります。
また、可読性の高いコードが書けるようになれば、より楽しく、効率的にプログラミングをする事が可能であると思います。自分自身、この事を意識し可読性の高いコードが書けるよう精進したいと思います。