分かりやすいコードの書き方

第９話：現場でのベストプラクティス

（最終更新日：2025.5.02）

実際の現場では‥‥

これまで、命名、関数分割、コメント、テスト、変更容易性と、分かりやすいコードのための技術や原則を見てきた。 今回は、実際の開発現場でどう活用するか、どうやってチームで徹底するか、レビューでどう育てるかなど、実践的なベストプラクティスを紹介する。

１.実際のプロジェクトでの成功例

1.1 後から読んでも迷わないバッチ処理のコード
複雑なCSV処理ロジックを、小さな関数に分けて「読み込み」「検証」「変換」「登録」を明確に分離した。 関数名とログメッセージに同じ用語を使うことで、処理の流れとログが一致し、障害対応もスムーズになった。 下記にその例を示す。読み込ませるCSVデータは以下の通りである。

これに対し、4つの分解した関数とそれをまとめた関数で処理する。

実際の処理結果が以下のようになる。最初のAliceのデータだけが登録され、他の2つはデータが不十分であることを注意されている。 4つの関数に分けて、名前も揃えたおかげで、各処理が非常に分かりやすい。そして、現在どの処理をしているのかが一目瞭然である。

1.2 データ駆動設計による拡張性の確保
これは、前回紹介したデータ駆動設計の例である。 「割引ルール」などをJSONで定義し、コードではそれを読み込んで処理する。 これにより、仕様変更のたびにロジックを書き換えなくても済む設計になる。変えるのはJSONデータだけで良い。

２.チームでコードを統一するための実践的な工夫

チームでコードを統一するための実践的な工夫を以下に箇条書きで示す。 ツールを上手く活用することで、書き方を矯正させることが大事だ。

• コーディング規約を軽量にまとめる：
  　　全員が読める形（例：README.md内、Notion、Confluence）に。
  　　必要最小限のルール（命名、インデント、コメント、ファイル構成など）に絞る。
• ESLint / Prettier / clang-format などを導入：
  　　自動整形・自動検出ツールをプロジェクトに組み込むことで、人が指摘しなくても良くなる
• フォルダ構成と命名に一貫性を持たせる：
  　　components/, services/, utils/ など役割ごとに明確に分類する。
  　　命名にプレフィックス・サフィックス（例：ButtonList, UserService）を共通化する。
• Git フックでコミット前にフォーマット／リント：
  　　husky + lint-staged で強制整形・静的解析を自動化する。

３.レビュー時に気をつけるポイント

レビューで気をつけるのは「構造」と「意図の伝わりやすさ」である。 ポイントは以下の通りだ。 コーディングスタイルの指摘は極力ツールに任せて、レビューでは意図や設計レベルの指摘に集中できるようにしよう。 これにより、コード品質が高まるはずだ。

• 関数の責務が明確か？ ： 1関数1目的になっているか
• 命名が具体的か？： handleClick より submitOrder のような意図が伝わる名前か
• 条件分岐が読みやすいか？： ネストが浅く、早期returnを活用しているか
• コメントが必要な場所にあるか？： 「なぜそうしたのか」が書かれているか

４.「悪いコード」を書かないためのチェックリスト

悪いコードを書かないためのチェックリストは以下の通りになる。 今までの復習にはなるが、全て大事なことなので、漏れずにチェックしよう。

• 命名は、処理の意図を明確に表しているか？
• 関数の長さは長すぎないか（目安：20行以内）？
• コメントで「なぜ？」を補足しているか？
• if文が深すぎないか？ 早期リターンで整理できないか？
• Magic Number（謎の数値）が埋まっていないか？
• ロジックが再利用可能な形になっているか？
• 将来的に仕様変更に強い設計になっているか？

５.まとめ

今回は実際のプロジェクトでの成功例を中心に説明した。 そのほかの部分は、今までのまとめになる。このように、「分かりやすいコード」は チーム全員で作り上げる文化だ。 規約・命名・構成・レビューを通じて、少しずつ育てていくことが大事だ。 そして、ツールに任せられる部分は任せて、人間は設計と意図の共有に集中する。 この分かりやすさの先にあるのが、安全・高速・拡張しやすいソフトウェア開発になる。 つまり、リファクタリングし続けられるSDGsなプログラミングコードだ。これを目指していこう。

▼参考図書、サイト

 「リーダブルコード」　Dustin Boswell、Trevor Foucher　著、角 征典　訳　オライリー