TypeScriptでコードの可読性を上げる方法と変更のしやすさについて考える

可読性の高いコードを書きたい

ソフトウェア開発において、コードの可読性は開発者にとって最も重要な要素の一つです。
誰もが悪意をもってわかりずらいコードを書こうとは思っていません。
現実に読みやすい、読みづらいコードが存在することは確かです…

可読性が高いコードが書ければ、開発チーム全体での理解やコミュニケーション（呼びやすい、意味のわかりやすい変数名）がスムーズになったり、デバッグするときに不具合箇所の特定、バグ修正が容易になります。

本記事では、簡単にコードの可読性を上げることができる方法を具体的な例を交えながら考えていきます。

---

1. 意味のある命名をする

最も簡単にできる改善の一つが、意味のある命名です。
変数名や関数名が曖昧であったり、冗長であるとコードの意図が読み取りにくくなり、理解に時間がかかります。また将来的にコードを変更する際、意味のある名前が付けられていると、変更箇所の特定や修正がスムーズに進みます。
わかりやすい変数名だと本当にデバッグするときなんか特に助かります…

悪い例

シンプルすぎる例

let x = 10;
let y = 20;
let z = x + y;

ここまでシンプルなことはないと思いますが…短い変数名は可読性低いですよね。

長すぎる例

let lengthOfTheProductAsMeasuredInCentimeters = 10;
let widthOfTheProductAsMeasuredInCentimeters = 20;
let areaOfTheProductAsCalculatedByMultiplyingLengthAndWidth = lengthOfTheProductAsMeasuredInCentimeters * widthOfTheProductAsMeasuredInCentimeters

この例では、変数名があまりにも長すぎて冗長です。何を意味しているのかはわかりますが、名前が複雑すぎて、コード全体が非常に読みにくくなっています。
また、変数名をここまで長くすると、1行のコードが画面を超えてしまい、エディタでの読みやすさが低下してしまいます。

良い例

let productLengthCm = 10;
let productWidthCm = 20;
let productArea = productLengthCm * productWidthCm;
}

ここでは、適度な長さで、変数の意味を十分に表している命名をしています。
productLengthCm という名前は、「商品の長さがセンチメートル単位である」という情報を十分に伝えており、かつ冗長になっていません。
productArea も、面積を表すための十分に意味のある名前であり、適切な長さです。
意味が通る変数名はチームでのコミュニケーションも円滑にさせると思います。
（質問したりレビューのときも時にどこの変数が〜みたいな話しやすくなりますよね）

2. 適切なコメントを活用する

コメントとして非常に有効ですが、注意が必要です。
コメントが多すぎたり、不要な箇所に書かれていたりすると、逆に可読性を下げてしまいます。
コメントは、コードの意図や特に複雑なロジックに対してだけ使い、自己説明的なコードを目指したいです。

悪い例

// 変数xに10を代入
let x = 10; 

// xを使って計算する
let result = x * 20;

良い例

// 商品の長さ（cm）
let productLength = 10;

// 商品の幅（cm）
let productWidth = 20;

// 面積を計算
let productArea = productLength * productWidth;

上記の例では、コメントは具体的ですよね。
また、変数名そのものが意味を持っているため、過度にコメントを付ける必要がありません。

3. コードの構造を整理する

コードの整理も可読性向上の重要なポイントであると思います。
大きな関数やメソッドを小さく分割し、各部分が1つの責任だけを持つようにすることで、コードは読みやすく、管理しやすくなります。

悪い例

function processOrder(order: any): void {
    if (!order) {
        console.error("Invalid order");
        return;
    }

    if (order.items.length === 0) {
        console.error("No items in order");
        return;
    }

    console.log("Processing order:", order);
    // データベースへの保存処理や、通知送信などの追加ロジックがここに入る
}

良い例

function processOrder(order: any): void {
    if (!isValidOrder(order)) {
        console.error("Invalid order");
        return;
    }

    saveOrder(order);
    notifyUser(order);
}

function isValidOrder(order: any): boolean {
    return order && order.items.length > 0;
}

function saveOrder(order: any): void {
    console.log("Order saved:", order);
    // データベースへの保存処理
}

function notifyUser(order: any): void {
    console.log("User notified for order:", order);
    // 通知の送信処理
}

このように、1つの大きなメソッドを小さなメソッドに分割することで、各メソッドの責任が明確になり、コードの意図がはっきりします。また、エラー処理や通知送信のような機能が別々に管理されるため、後での変更や拡張も簡単です！

4. 条件式をシンプルにする

条件式は、複雑になるとコードの可読性を大幅に下げます。ネストが深い条件文は特に読みづらく、バグが入り込みやすいです。これを避けるためには、条件式を分解してシンプルにすることが効果的です。

悪い例

if (user != null && user.isActive && user.role === "admin") {
    // 処理
}

良い例

function isUserAdmin(user: any): boolean {
    return user != null && user.isActive && user.role === "admin";
}

if (isUserAdmin(user)) {
    // 処理
}

ここでは、条件式を関数に分離することで、条件が複雑な場合でも、コードがすっきりし、何をチェックしているのかが明確になります。

---

まとめ

可読性の高いコードを書くためには、意味のある命名、適切なコメントの活用、コードの整理、条件式のシンプル化といったポイントに注意することで比較的簡単にあげられます。
簡単ですが意外と意識していないとできていなかったりすることなのかなと思います。
常に意識しながら可読性の高いコードを書いていくようにしたいです！

---