1. はじめに
チーム開発では、他人が書いたコードを読む機会が多いです。
「このメソッド、なんでここでこの処理してるんだ?」
「このテーブル結合、どういう意図?」
「変数名が抽象的すぎて何が入ってるか分からん...」
基礎文法は分かる。自分でコードも書ける。
でも、他人のコードを読むのは別スキルだと痛感することも少なくありません。
この記事は、わたし自身が「他人のコードから仕様を理解する力」を
どうやって鍛えているか、試行錯誤の記録です。
わたし自身、まだまだ試行錯誤中ですが、
この記事が同じように悩んでる人の参考になれば嬉しいです。
2. 現場でよくあること
具体例:
プロジェクト参加初日。
リーダーから指示「この機能、バグ修正お願いします」
期待していたもの:
- 仕様書
- 設計書
- せめてコメント
実際にあったもの:
- 3年前に書かれたコード
- テーブル定義(カラム名のみ)
- 「多分このあたりです」というSlackのリンク
「ドキュメント? そんなのないです」
メモ:
- 現場あるある「コードが仕様書」
- たとえドキュメントがあっても古くて使えない
- 実装とドキュメントが食い違ってることも！
3. 【具体例】「コードから仕様を理解する」プロセス
3-1. まず全体像を掴む
悪い例(以前の自分):
いきなりコードを上から読み始める
→ 詳細に迷い込んで、何のための処理か分からなくなる
改善後:
1. エントリーポイントを探す(Controller, API handler)
2. 処理の流れを図に書く(手書きでOK)
リクエスト → バリデーション → DB取得 → 加工 → レスポンス
3. 各ステップで「何を入力して、何を出力するか」を書き出す
実例:
ECサイトの注文確定API読解時
POST /api/orders
↓
OrderController.create
├─ リクエストから注文データ取得
├─ 在庫チェック(InventoryService)
│ └─ productsテーブルとstock_logsテーブルを確認
├─ 金額計算(PriceCalculator)
│ └─ 商品単価 × 数量 + 送料 - クーポン
└─ トランザクション開始
├─ ordersテーブルINSERT
├─ order_itemsテーブルINSERT
└─ stocksテーブルUPDATE
成功時: 注文番号返却
失敗時: ロールバック & エラーレスポンス
簡単な図を最初に書くだけで、後が圧倒的に読みやすくなります。
3-2. 実際に動かして確認する
動かすことで、さらに理解が進みます。
やったこと:
-
ローカル環境でデバッガ起動
- VSCodeのブレークポイントを各処理の前後に置く
- 変数の中身を実際に見る
-
テストデータで試す
- 正常系: 普通に注文してみる
- 異常系: 在庫0で注文、存在しない商品ID、etc.
- 各パターンでどこを通るか確認
-
SQLの実行結果を見る
- ログからSQL文をコピー
- DB管理ツールで実際に実行
- 「あ、このJOINでこのデータが取れるのか」が分かる
具体例:
# このコードを読んでもピンと来なかった
orders = Order.joins(:items)
.where(user_id: user.id, status: 'pending')
.group('orders.id')
.having('SUM(items.price * items.quantity) > ?', 10000)
実際にSQLログを確認:
SELECT orders.* FROM orders
INNER JOIN order_items items ON items.order_id = orders.id
WHERE orders.user_id = 123 AND orders.status = 'pending'
GROUP BY orders.id
HAVING SUM(items.price * items.quantity) > 10000
→「合計金額1万円超えの未確定注文を取得してるのか!」と理解。
3-3. テーブル構造から逆算する
コードだけでなく、DBも見て理解を深めます。
やり方:
1. 関連テーブルのER図を自分で書く
2. 外部キーの関係を矢印で繋ぐ
3. 「このテーブルとこのテーブルが紐づいてるなら、
こういうデータ構造なんだろう」と推測
4. コードと照らし合わせる
実例:
usersテーブル
↓ (1対多)
ordersテーブル
↓ (1対多)
order_itemsテーブル
↓ (多対1)
productsテーブル
この構造が分かれば:
- 「ユーザーは複数の注文を持てる」
- 「1つの注文には複数の商品が含まれる」
- コードで
user.orders.includes(:items)と書いてある意味が分かる
4. 他人のコードを改修するときの心構え
実際にあった失敗:
既存コードを「汚い」と思って全部書き直した
→ レビューで「なんでこのロジック変えたの?」と指摘
→ 実はビジネスロジック上の理由があった
学んだこと:
1. まず「なぜこう書かれているか?」を考える
2. 変更前にチームメンバーに確認
3. 「この処理、〇〇という理解で合ってますか?」と聞く
4. 理解できてから修正する
改修時のチェックリスト(自分用):
- この修正で影響する範囲は?
- 関連する他の機能は?
- テストは通るか?
- 既存の仕様を壊していないか?
5. 【３つの習慣】効率的コード理解
やって良かったこと:
-
コードリーディング会に参加
- 週1でチームメンバーと特定の機能を読む
- 「ここ、こういう意図ですよね?」と確認できる
-
自分用のメモを残す
- 「このクラスは〇〇を担当」
- 「この処理の前提条件: △△」
- Notionやmarkdownで管理
-
小さい機能から読む
- いきなりコアな複雑な機能は読まない
- ログイン、ログアウトなど単純な機能から
やらなくて良かったこと:
- 全コードを完璧に理解しようとする
→ 必要な部分から理解すればOK - コメントを期待する
→ ないのが前提で読む
6. まとめ
「他人のコードを読む」のは最初こそ苦痛ですが、
亀の歩みでも継続することで、少しずつ理解が進みます。
重要なのは:
- 実際に動かして確認する
- 全体像から詳細へ
- 分からないことは人に聞く
わたし自身、まだまだ試行錯誤中ですが、
この記事が同じように悩んでる人の参考になれば嬉しいです。