他人が書いたコードを読むとき、AIに説明させながら進める
引き継いだサイトのコードが読めませんでした。全体から降りていく順番の話です。

この記事の結論
- 最初から詳しく読もうとすると進まない
- 全体の構成から、少しずつ降りていく
- 触る必要がある箇所だけ、深く読む
- 最初から詳しく読もうとすると進まない
- 全体の構成から、少しずつ降りていく
- 触る必要がある箇所だけ、深く読む
他の人が作ったサイトを引き継いだとき、どこから手を付けるか分からなかった。読み進める順番を決めた記録を書く。
最初にやった失敗
いきなりファイルを開いて読み始めた。
- どこが重要か分からず、全部読もうとした
- 関係ない部分に時間を使った
- 全体像が掴めないまま、細部で迷った
3つ目が問題だ。部分を読んでも、全体の中での位置が分からない。
全体の構成から聞く
まず、ファイルの一覧を渡して聞いた。
次はサイトのファイル構成です。
(一覧を貼る)
- 全体がどういう構成か
- どのファイルが中心的か
- 表示に関わるのはどれか
中身はまだ見ていません。名前から推測で構いません。名前から推測させるだけでも、当たりが付く。
中心的なファイルから読む
当たりが付いたら、そこから読む。
- 1ファイルずつ渡す
- 「何をしているファイルか、5行で」と聞く
- 詳しい説明は、必要になってから
3つ目が要点だ。最初から詳しく読んでも、使わない知識が増える。
触る箇所を特定する
やりたいことが決まっているなら、そこから逆に辿る。
この画面の「(部分)」を変えたいです。
どのファイルのどのあたりを見ればよいですか。
構成は次の通りです。
(一覧)全部読まなくても、触る箇所にたどり着ければ作業できる。
そのまま使える形
全体を説明させると、分かった気になって終わる。入口と出口から辿る。
このコードについて、処理の中身はまだ説明しないでください。 1. 外から呼ばれる入口はどこか(関数名・ファイル名) 2. 最終的に何が変わるのか(画面の出力/保存される値/送信されるもの) 3. 入口から出口までに通る関数を、順番だけ列挙 これが分かってから、中身を聞きます。
先に経路が見えていると、どこを読まなくてよいかが決まる。読む量を減らすのが目的だ。
読む順番
やってみて、この順が進みやすかった。
- ファイル構成を見る
- 設定ファイルを読む。全体の方針が書かれている
- 入口になるファイルを読む
- 触る箇所を特定して、そこを深く読む
2つ目を先にやると理解が速い。設定には、作った人の方針が表れる。
危ない箇所を把握する
触る前に、触ってはいけない場所を確認している。
- 更新で上書きされる場所
- 他の部分から参照されている共通の処理
- 意図が分からないが、消すと壊れそうな記述
3つ目は残す判断にしている。理由が分からないものは、理由があると考える。
コメントを足す
読んで分かった内容は、その場に書き残している。
- 何をしている部分か、1行書く
- 調べて分かった意図を書く
- 自分が変更した箇所は、日付と理由を書く
3つ目が後で効く。半年後の自分は、他人と同じ。
作った人の意図を推測する
読んでも理由が分からない記述に、何度か当たった。
- コードを渡して「なぜこう書いたと考えられるか」と聞く
- いくつか可能性を挙げさせる
- どれが当たっているか、他の箇所と照らして判断する
2つ目が役に立った。「特定の環境への対応」「過去の不具合の回避」「単に古い書き方」など、候補が出る。候補があると、どれかを調べる足がかりになる。理由が分かれば消してよいか判断できるし、分からなければ残す。推測を事実として扱わないことだけ気をつけている。
全部を理解しようとしない
途中で方針を変えた。
- 全体を理解するのは、目的ではない
- 触る箇所と、その周辺が分かれば足りる
- 必要になったときに、また読めばよい
2つ目を基準にしてから、作業が進むようになった。理解することと、作業することは別だ。
変更の影響を調べる
1か所直す前に、どこに影響するか確認している。
- その関数や部品が、どこから呼ばれているか検索する
- 呼ばれている箇所を一覧にする
- すべての箇所で、変更後の動きを確認する
1つ目は、ファイル内の検索で足りる。名前で検索すれば、使われている場所が出る。共通の処理を直すと、思わぬ場所が壊れるのは、どの環境でも同じだった。引き継いだコードは、どこで何が使われているか把握していないので、特に注意している。
記録を残す
読んで分かったことは、別に記録している。
- どのファイルが何をしているか、一覧にする
- 変更した箇所と、その理由
- 触ってはいけない箇所と、その理由
3つ目が最も重要だった。次に触る人への引き継ぎになる。
あわせて読む
- 引き継いだコードを、どこから読むか — 人が書いたものを触る前に、読む順番を決めました。
- 色やサイズを変数にしたら、後から変えるのが楽になった — 同じ値を何か所にも書いていました。まとめた後の違いを書きます。
- 読めないコードを書かせないために、頼み方を変えた — 短く書かれると読めません。自分が読める範囲で書いてもらう話です。
まとめ
- 最初から詳しく読もうとすると進まない
- ファイル構成から、当たりを付ける
- 設定ファイルを先に読むと、方針が分かる
- 理由が分からない記述は、理由があると考えて残す
- 全体の理解は目的ではない。触る箇所が分かれば足りる
新しい記事が出たら、ブラウザの通知でお知らせします。
メールアドレスの登録は要りません。いつでも止められます。
関連記事
RELATED
圧縮できるのは、冗長度があるから。情報の量の測り方を図にした
情報の量は意味では測りません。どれだけ絞り込めたかで測ります。1948年の論文が置いた定義と、英語の冗長度が約50%とい…
HOKKAIDO AI LAB を英語でも読めるようにしました。ボタン1つで翻訳、英語のページを作らなかった理由も
海外から読んでくださる方のために、ヘッダーに英語の翻訳ボタンを付けました。押すと、いま見ているページがその場で英語になり…
相席か個室か。1つの仕組みを何社で使うかを図にした
共有するか分けるかは0か1ではありません。層ごとに決められます。4つの構成と、それぞれで何を引き受けることになるのかを整…