クリーンコード

クリーンコードとは

クリーンコードとは、他人が読んですぐ理解でき、安心して変更できるコードのことです。Robert C. Martin の同名の著書で広く知られるようになりました。

前提として、コードは書かれる時間よりはるかに長く読まれます。半年後の自分も「他人」です。動くコードを書くのは最低条件であり、その先の「読めるか」「直せるか」までが品質だと考えるのがこの考え方の出発点です。

命名がすべての土台

読みやすさに最も効くのは命名です。

const DISCOUNT_RATE = 0.1;

function calc(d, f) { return d * f * 0.1; } // 読みにくい

function calculateDiscountAmount(price, quantity) { // 意図が伝わる
  return price * quantity * DISCOUNT_RATE;
}

• 意図を表す名前にする — d ではなく price。省略は読み手の負担になります
• マジックナンバーに名前を付ける — 0.1 を DISCOUNT_RATE にすれば、意味と変更箇所が明確になります
• 関数名は動詞から始める — getUser、calculateTotal、isValid
• 名前が長くなるのは悪ではない — 補足コメントが要る短い名前より、説明的な長い名前のほうが優れています

「よい名前が思いつかない」ときは、そのコードの責務が曖昧なサインです。名前の悩みは設計の悩みでもあります。

関数とコメントの扱い

コメントについては、コメントで説明しないと分からないコードは、まずコードを直すのが基本です。// ユーザーがアクティブかチェックする と書いて if (u.s === 1) を残すより、if (user.isActive()) とコード自身に語らせるほうが優れています。

一方で、「なぜ」を書くコメントは価値があります。「この順序で処理しないと外部APIが400を返すため」といった、コードからは読み取れない背景は積極的に残しましょう。

DRY と、やりすぎない線引き

DRY(Don't Repeat Yourself)は、同じ知識をコードの複数箇所に持たないという原則です。同じ計算ロジックが3箇所にあれば、修正のときに1箇所を直し忘れます。ただしDRYは「見た目が似ているコードをすべて共通化せよ」ではありません。たまたま似ているだけの処理を無理に1つにまとめると、片方の仕様変更のたびに分岐が増え、かえって複雑になります。同じ理由で一緒に変わるものだけをまとめる、が正しい捉え方です。

実務での身につけ方

• 完璧なコードを最初から書こうとしない。動かしてから [[リファクタリング]] で整える
• [[コードレビュー]] で「読みにくい」と言われたら、それは事実です。読み手が詰まった時点で改善余地があります
• 安心して直すには [[自動テスト]] が要ります。テストがあるからこそ思い切って整理できます
• 「後で直す」を積み重ねた結果が [[技術的負債]] です。小さな汚れはその場で拭くのが最も安く済みます
• よくある構造の整理には [[デザインパターン]] という共通言語があります。ただしパターンを使うこと自体を目的にしないよう注意しましょう

初学者向けポイント

• ボーイスカウトルール — 「来たときよりも美しく」。触ったファイルを少しだけ綺麗にして帰る習慣が効きます
• 自分のコードを翌日に読み返しましょう。詰まった箇所が、そのまま改善ポイントです
• 整形や命名規則のチェックは [[静的解析とリンター]] に任せ、人は設計の議論に時間を使いましょう

関連技術とのつながり

• [[リファクタリング]] — 動作を変えずに読みやすさを改善する具体的な手段
• [[コードレビュー]] — 読み手の視点で品質を確認する場
• [[デザインパターン]] — よくある構造に名前を付けた共通言語
• [[技術的負債]] — クリーンでないコードが将来のコストとして積み上がる
• [[自動テスト]] — 安心して直せる土台を作る

Q: クリーンコードが重視する前提はどれ?
- [x] コードは書かれる時間よりはるかに長く読まれる
- [ ] コードは短ければ短いほどよい
- [ ] コメントを大量に書けば読みやすくなる
解説: 読まれる時間が長いからこそ、他人が理解でき安心して変更できることを重視します。

Q: コメントの使い方として推奨されるものはどれ?
- [ ] コードの処理内容をそのまま日本語に翻訳して書く
- [x] コードからは読み取れない「なぜ」を書く
- [ ] コメントは一切書かない
解説: 処理内容はコード自体で語らせ、背景や理由といったコードに表せない情報をコメントに残します。

Q: DRY原則の正しい捉え方はどれ?
- [ ] 見た目が似ているコードはすべて共通化する
- [x] 同じ理由で一緒に変わるものだけをまとめる
- [ ] 関数は必ず10行以内にする
解説: たまたま似ているだけの処理を無理に共通化すると、仕様変更のたびに分岐が増えてかえって複雑になります。