他人が書いたコードを読むとき、どこから確認する？

エンジニアとして仕事をしていると、自分が一から作ったプログラムだけを扱うとは限りません。
むしろ実際の現場では、
「以前別の人が作ったシステムを改修する」
「既存機能に新しい処理を追加する」
「不具合の原因を調査する」
「担当者が変わり、途中から引き継ぐ」
といった形で、他の人が書いたコードを読む機会も多いと思います。
しかし、初めて見るプログラムを開いたときに、
「どこから読めばいいのか分からない」
と感じた経験がある方もいるのではないでしょうか。
今回は、既存のコードを読むときに、どのような順番で確認すると理解しやすいのかについて考えてみます。

最初からすべて読もうとしない

初めて見るコードを理解しようとするとき、ファイルの先頭から順番にすべて読もうとしてしまうことがあります。
しかし、大きなシステムになるほどファイル数もコード量も多くなります。
すべてを最初から理解しようとすると、時間がかかるだけでなく、
「結局どこが重要なのか分からなくなった」
という状態になることもあります。
そのため、まずはシステム全体ではなく、
「今回自分が確認したい処理はどこなのか」
を明確にすることが大切です。
たとえば、
「ログインボタンを押したあとの処理を確認したい」
のであれば、ログイン処理に関係する部分から追っていきます。
既存コードを読むときは、すべてを理解してから作業するのではなく、必要な範囲から理解していく方が効率的です。

まずは処理の入口を探す

コードを読むときに最初に探したいのが、
処理が始まる場所
です。
Webシステムであれば、
・ボタンを押したときの処理
・APIの呼び出し部分
・画面を開いたときに実行される処理
などがあります。
バッチ処理であれば、実行開始部分やメインとなる関数を確認します。
まず入口を見つけたら、
「この処理から次にどの関数が呼ばれているのか」
を順番に追っていきます。
最初から細かいコードをすべて理解しようとするよりも、
「AからBが呼ばれて、そのあとCが実行される」
というように、大まかな流れをつかむことを優先します。

入力と出力を見る

処理の内容が分かりにくい場合は、
何を受け取って、何を返しているのか
を見る方法も有効です。
たとえば、ある関数が、
「ユーザーIDを受け取って、ユーザー情報を返す」
処理であれば、その関数の役割はある程度予想できます。
さらに、
・引数には何が渡されているのか
・戻り値はどこで使われているのか
・データの形式は何か
を確認すると、処理の目的が見えてきます。
細かいロジックを読む前に、入口と出口を確認するだけでも、そのコードが何をするためのものなのか理解しやすくなります。

関数名や変数名から役割を予想する

コードを読むときには、関数名や変数名も重要な手がかりになります。
たとえば、
getUserData
という関数であれば、
「ユーザー情報を取得する処理なのかな」
と予想できます。
saveData
であれば、何らかの情報を保存する処理だと考えられます。
もちろん、必ずしも分かりやすい名前が付けられているとは限りません。
略語や独自の命名ルールが使われている場合もあります。
そのような場合は、
「この変数がどこで値を入れられて、どこで使われているのか」
を検索すると役割を理解しやすくなります。
名前だけで判断するのではなく、実際の使われ方と合わせて確認することが大切です。

処理を追うときは「どこから来て、どこへ行くか」を見る

コードを読んでいると、途中で別の関数が呼ばれたり、別のファイルに処理が移ったりします。
そのたびに細かい内容を調べていると、最初に何を確認していたのか分からなくなることがあります。
そのため、
「このデータはどこから来たのか」
「この処理の結果はどこで使われるのか」
という流れを意識すると理解しやすくなります。
たとえば、
画面から入力された値が、
「画面 → API → 処理クラス → データベース」
という順番で渡されているのであれば、まずはこの流れを把握します。
それぞれの細かい処理は、そのあと必要に応じて確認していきます。

コメントをそのまま信じすぎない

既存コードにはコメントが書かれていることがあります。
コメントは処理を理解するための重要な情報ですが、注意も必要です。
プログラムが後から修正されたにもかかわらず、
コメントだけ古いまま残っている
ことがあるからです。
たとえば、
「ユーザー情報を削除する処理」
とコメントされているのに、実際には削除ではなく無効化する処理に変更されている場合があります。
そのため、
「コメントにこう書いてあるから、この処理のはずだ」
と決めつけず、実際のコードも確認することが大切です。
コメントはあくまで理解を助ける情報として利用し、最終的には処理そのものを見る必要があります。

分からない処理は一度動かしてみる

コードを読んでいるだけでは、どうしても理解しにくい場合があります。
そのようなときは、可能であれば実際に動作を確認してみる方法もあります。
たとえば、
・ログを追加する
・変数の値を確認する
・デバッガーで処理を止める
・入力値を変更して動きを見る
といった方法があります。
コード上では複雑に見えていた処理でも、
「この値が入ったときだけ、この条件に入る」
と実際の動きを見ることで理解できることがあります。
ただし、本番環境のコードを直接変更するのは危険です。
可能であれば開発環境や検証環境を使って確認することが重要です。

Gitなどの変更履歴もヒントになる

既存コードを理解するうえで、変更履歴も役立ちます。
Gitなどのバージョン管理が使われている場合、
「いつ追加された処理なのか」
「誰が変更したのか」
「どのような目的で変更されたのか」
を確認できることがあります。
特に、
「なぜこの処理が必要なのか分からない」
というコードがあった場合、過去のコミットメッセージや変更内容を見ることで理由が分かることがあります。
一見すると不要に見えるコードでも、
「以前発生した不具合への対策」
として追加されている可能性があります。
そのため、理由が分からない処理をすぐ削除するのではなく、まず変更履歴を確認することも大切です。

修正する前に影響範囲を確認する

既存コードを読む目的が改修である場合、
「ここを直せば動きそう」
と思っても、すぐ変更するのは少し危険です。
その処理が別の機能からも利用されている可能性があります。
たとえば、共通関数を修正したことで、
「目的の画面は正常になったが、別の画面が動かなくなった」
ということもあります。
そのため、修正前には、
・その関数が他でも使われていないか
・共通処理ではないか
・データ形式を変更して問題ないか
・他の画面や機能への影響がないか
を確認することが大切です。
コードを理解することと、影響範囲を理解することはセットで考える必要があります。

分からないところをメモしておく

既存システムを調査していると、
「この処理は何のためにあるのだろう」
という部分が次々に出てくることがあります。
そのたびにすべて調べていると、調査がなかなか進みません。
そのため、今すぐ理解する必要がないものについては、一度メモして後から確認する方法も有効です。
たとえば、
「この変数の用途はあとで確認」
「この関数は今回の修正には関係なさそう」
というように整理します。
調査範囲を広げすぎないことも、既存コードを読むときには大切です。

他人のコードを読むこともスキルの一つ

プログラミングというと、
「コードを書く能力」
に注目されることが多いですが、実際の仕事ではコードを読む時間もかなりあります。
既存システムの改修、不具合調査、コードレビュー、引き継ぎなど、コードを読む力が必要になる場面は多くあります。
また、他の人が書いたコードを見ることで、
「こういう書き方もあるのか」
「この処理はこう分けると分かりやすい」
といった気づきを得ることもあります。
反対に、
「この書き方だと後から読むのが大変だな」
と感じることもあり、自分がコードを書くときの参考にもなります。

まとめ

他人が書いたコードを読むとき、最初からすべてを理解しようとする必要はありません。
まずは、
・今回確認したい処理を決める
・処理の入口を探す
・入力と出力を確認する
・大まかな処理の流れをつかむ
・必要な部分だけ詳しく調べる
・変更履歴や実際の動作も確認する
・修正前に影響範囲を見る
という順番で進めると理解しやすくなります。
既存コードを見ると、最初は複雑に感じることもあります。
しかし、一つずつ処理を追っていけば、少しずつ全体像が見えてきます。
コードを書く力と同じように、
「他人が書いたコードを読み解く力」
これも、エンジニアとして仕事をするうえで大切なスキルの一つではないでしょうか。