目次

はじめに
注意点

可読性はなぜ考慮する？
ナンバリング変数(ナンバリング命名)
ハードコーディング(マジックナンバー)
フラグ引数メソッド

まとめ

はじめに

　現役Webエンジニアのよっしーです。
　本記事では、主に学生さんや新人エンジニアさん向けにコーディングの可読性理念について紹介します。

注意点

書籍、インターネットで得た知見、及び筆者の考えが含まれています。
基本的に、紹介に挙げた理念以外については考慮していないものとお考え下さいませ。
ソースコードはjsとしていますが、あくまでも概念を伝える事が目的のため、簡略化している部分があります。

上記を踏まえた上でご覧ください。

1. 可読性はなぜ考慮する？

　一番の理由は「開発担当者以外が見てもわかるようにするため」だと筆者は思います。
　実務では、自分のコードを誰かが見る機会が沢山あります。「複雑に見えてしまうコード」「その場しのぎなコード」が多くあると、後任さんや未来の自分が頭を抱えてしまいます。。。
　複雑な処理もできるだけわかりやすくし、「プログラマーなら誰が見てもすぐ理解できる」コードを目指しましょう。

2. ナンバリング変数(ナンバリング命名)

　ナンバリング変数とは、変数にナンバリングを付けたものを言います。
　そのまんまの意味ですね。

ナンバリング変数の使用例

function method1(num1){
    const num = num1 * 2.0;
    return num;
}

　ナンバリング変数を使用すると、何に使われる変数なのか見ただけでは判断できません。num1、num2とあっても、num1が何を示すのかわかりませんよね。method1も何をするメソッドなのかわかりません。

対策例

function calculateBonus(basicSalary){
    const result = basicSalary * 2.0;
    return result;
}

　これなら、何を表現しているのかわかりやすいですね。ナンバリング変数に限らずですが、何を表す変数・メソッドなのかわかりやすい命名を心掛けましょう。

3. ハードコーディング/マジックナンバー

　ハードコーディングとは、よく使われる固定値などをコード内で直接記述することです。
マジックナンバーとは、どういうものなのかわからない数値を指します。
状況によりますが、この二つは基本セットになることが多いです。

マジックナンバーの使用例

function calculateBonus(basicSalary){
    const result = basicSalary * 2.0;
    return result;
}

　実はこのコードにはNGが残っていました。「2.0」の部分ですね。この数字が、明白に何なのかわかりません。これが「マジックナンバー」という状態です。さらに、下記のような状態だとどうでしょう。

ハードコーディングの使用例

// 一般社員の賞与計算
function calculateBonus(basicSalary){
    const result = basicSalary * 2.0;
    return result;
}

// 主任の賞与計算
function calculateBonusOfChief(basicSalary){
    const result = basicSalary * 2.0;
    return result;
}

　「2.0」がどちらにも使われています。これが「ハードコーディング」という状態です。仮にこの「2.0」が「3.0」に仕様変更となった場合、どちらも修正しなくてはいけません。

対策例

// 賞与倍率
const BONUS_MULTIPLIER = 2.0;

// 一般社員の賞与計算
function calculateBonus(basicSalary){
    const result = basicSalary * BONUS_MULTIPLIER;
    return result;
}

// 主任の賞与計算
function calculateBonusOfChief(basicSalary){
    const result = basicSalary * BONUS_MULTIPLIER;
    return result;
}

　「2.0」を「BONUS_MULTIPLIER」という定数として宣言しました。これで「2.0」が何のための数値なのか明白になりました。また、一元管理できるようになったため、仕様変更の際はこの変数の値のみを書き換えればよくなりました！
※実務では、一つのファイルに定数をまとめて扱う事が多いです。

4. フラグ引数メソッド

　フラグ引数メソッドとは、引数の値によって処理が変わってしまうメソッドのことを指します。

フラグ引数使用例

    function calcration(num,num2,flg){
        if(flg === 1) return num + num2;
        if(flg === 2) return num - num2;
        if(flg === 3) return num * num2;
        if(flg === 4) return num / num2;
    }

　これは「単一責任の原則」という考え方の元NGと判断します。単一責任の原則とは「1つのモジュールにはたった1つの役割を持たせる」という考え方です。
　これを守らないとテストが複雑になったり、不具合発見時や改修時の影響範囲特定に時間がかかったりして、担当者のメンテナンス性を大きく損ねます。

対策例

const sum = calculateSum(num, num2);
const difference = calculateDifference(num, num2);
const product = calculateProduct(num, num2);
const quotient = calculateQuotient(num, num2);

function calculateSum(num,num2){
        return num + num2;
}
function calculateDifference(num,num2){
        return num - num2;
}
function calculateProduct(num,num2){
        return num * num2;
}
function calculateQuotient(num,num2){
        return num / num2;
}

　四則演算を4つのメソッドに分離し、flgによって呼び出し先を変える処理にしました。これにより各メソッドは各四則演算の役割のみを持ち、単一責任の原則に基づきます。

まとめ

　本記事では、可読性理念のごく一部を紹介しました。学校の授業や新卒研修では、このような理念に触れることは多くないと思います。
　美しいコードを書いて、自他共に良い気持ちになれるよう、意識していくと良いでしょう。

参考

https://gihyo.jp/book/2022/978-4-297-12783-1
その他社内研修等