入社直後！コード解析の進め方(Webアプリケーション) | Offers Tech Blog

はじめに

こんにちは。
プロダクト開発人材の副業転職プラットフォーム Offers を運営する株式会社 overflow のエンジニアの藤井です。
2022/10 月に入社したばかりの新人(社内最年長)でございます。

エンジニアであれば誰しも新しい職場にジョインした直後から、未知のコードや事業ごとのドメイン知識をキャッチアップして仕事を進めていかなければなりません。
とはいえ、すでに何年も前から事業とシステムは動き続けているわけですから、大抵は既存のコードを含め情報は膨大なはず。
一度に全部を学ぶことなど、認知限界のある人間には不可能です。

そこで、どのような切り口でコードを解析し、システムの理解を進めていくべきか、今回の私自身の入社体験から一例としてご紹介させていただきます。
(このあたりの手順を言語化した記事をあまり見たことがないので)

なお、弊社のシステムが Web アプリケーション (RoR+Vue.js) なので、解析の進め方もそれに特化したものとなっております。
あらかじめご了承ください。

事前準備

さて、何はするにもまずは準備が必要です。
MacBook Pro を渡され、セットアップが完了した後は、どこの会社も大体以下のようなステップを踏むのではないでしょうか？

• リーダーから説明を受ける (開発フローとか、チーム体制とか)
• 開発環境を構築する
• 最初のタスクを受ける

最初のタスクを受けた時点で、自動的に以下のような目標が生まれます。
※仮に上長から明確に指示されなくても、暗黙的に期待されているはずです。

1. 開発タスクを完了させる
2. タスクに直接的に関連する業務知識やシステムについて理解する
3. ついでに間接的な情報を吸収して、事業やシステム全体の文脈を理解する

まず 1. は仕事そのものなので当然ですね。 2. も、なかば 1. の付帯条件なので必須でしょう。 Why を知らぬままに What は作れません。

しかし、この時点で最も大事なのは、 3. でしょう。
事前準備としても、ここを意識した上で少し広めに情報を収集していく必要があります。
ただし、この段階では全部の情報を深掘りしていては時間がいくらあっても足りないので、まずはどこに何の情報があるのかを知ることを第一の目標にします。

また、セキュアであるべき情報に対しては閲覧制限が施されている場合も多いでしょう。
そういった情報に対して必要に応じて権限を与えてもらうよう、リーダー等に交渉することもこの時点でやっておくべきことの 1 つでしょう。
もちろん作業の途中でアクセスが必要な情報を発見したら、都度しかるべき人と相談するようにします。

アクセスを得るべき情報の例

• ソースコードの格納場所
• 要件定義書や、ER 図などの技術資料の場所
• サーバ等のインフラリソースの場所
• ログ、アラートの場所

アプリケーションを動かしての調査

必要な情報へのアクセスを確立したら、開発用の環境で実際にアプリケーションを動かしていきます。
私は基本バックエンドが担当なので、今回はコード解析もそちらを中心に進めました。

バックエンド側の解析

HTTP => Controller

まず、バックエンド側の解析を進めるためには処理の入口となる API と、 API に紐づく処理( MVC モデルなら Controller )を特定する必要があります。

1. 実際に画面を操作して、開発対象となる画面や操作を特定する
2. Chrome の開発者ツールなどで HTTP の通信ログを確認する
3. 特定の操作で発行される API のログを探し、作業メモに記録する
4. サーバ側のルーティングを確認し、 HTTP メソッド + URL パスからから API に対応するコントローラを特定する

Web アプリのフレームワークであれば HTTP リクエストのルーティング用の定義ファイル (e.g. config/routes.db) があるはずなので、そこを調べます。

なお、余談ですがこの定義ファイルが Fat だったり、リーダブルでなかったりすると後から参加するエンジニアが苦労することになります。
そういった場合、すぐに grep できるように紐づく URL をコメントで書いておいてもいいかもしれませんね。

Controller => Model

エントリとなる Controller を特定すれば、そこから API の I/F 要件も踏まえてビジネスロジックを読み解いていきます。
この際、GraphQL や OpenAPI のようにスキーマ駆動で開発すれば API の I/F 要件が明確なので問題ないのですが、古い REST API だと I/F 要件がコードから読み取れないケースがあったりします。

PHP の array や Ruby の Hash を下位処理に丸投げするようなコードは基本、悪ですね。
Rails の Strong Parameters とか悪から生じた必要悪のような感じがします。

今回は残念ながらそういったコードに遭遇したので、画面を何度も操作しながら I/F 要件を改めて洗い出す作業をしました。
(おかげで古い REST API はさっさと GraphQL に移行しようという揺るぎない決意が生まれました)

CleanArchitecture なら Use Cases 層がビジネスロジックにあたりますが、 Rails の場合は大体 Model です。
なお、個人的には concerns にビジネスロジックを書くのはナンセンスだと思っています。
ビジネスロジックに特化したクラスや階層を作りたい派ですが、 Rails Way から外れたくもないので、目下、社内で議論されているところです。

ビジネスロジックの過程で登場する Model をすべて特定し、コールバック機構にも注意しながら順番に処理を追いかけていきます。
※ IntelliJ IDEA のコードジャンプが優秀なので、長年個人でライセンスを購入して使い続けています。

Model 周辺は処理の要なので、きっちり時間をかけて読み込んでいきます。
正確には計測していませんが、おそらくコードリーディングでは Model に一番時間を使っています。

Model => Database

ビジネスロジックの処理フローと Model の挙動を把握したら、次に DB クエリを確認します。
大体、アプリケーションログに DB クエリが記録されているので、ER 図や DB スキーマの定義ファイルなどを参照しながら、データの関係性や役割、属性の意味をつかんでいきます。
テーブル名から関係性を把握できることも多いですね。名前重要。

話は脇道にそれますが、アプリケーションログをまったく確認せずに開発するのは、ほとんど冒涜的な所業です。(個人の感想です)
N+1 が出ていてもまず気がつきませんし。

ともあれ大体ここまでキャッチアップが進むと、事業ドメインに関わる各情報がどこで永続化されているのか、どういった操作でどのデータが更新されるのかといった脳内地図が徐々に出来上がり始めます。
視界が開け、慣れない環境で作業を続ける不安も和らぎますが、同時に疑問も増えているはずです。

いわゆる「わからないことがわからない」レベルから「わからないことがわかる」レベルへ一歩段階が進んだ段階ですね。

そういった疑問点はメモに残して仕分けし、必要に応じて人に質問したり、ドキュメントを確認したりします。

これによって、最初の目標のひとつだった「3. ついでに間接的な情報を吸収して、事業やシステム全体の文脈を理解する」を進展させることができます。

その他

DB ヘの書き込みだけではなく、メールの通知や特殊なロギングなど、システムが行っていることは多岐にわたるはずです。
特にシステム外部へ通信するような処理は INFO レベルのログでぱっと確認できるのが理想です。

もしもログを見てもすぐには処理が追えない場合は、ログ自体を見直すいい機会になるかもしれません。

フロントエンド側の解析(おまけ)

フロントエンド側を解析する際もまずは処理のエントリを特定することから始まります。
私の場合、大体以下の手段でエントリを見つけることが多いです。

• HTML 要素の ID やクラス属性からコードを逆引きし、ボトムアップで調査
• HTTP ログの API の URL からコードを逆引きし、ボトムアップで調査
• index.js など全体のエントリからトップダウンで調査

今回は私の担当箇所では、既存実装が Rails の erb で一旦 HTML を書き出し、 SCRIPT タグからフロントエンド側の JS を呼び出すようになっていました。
一部データは HTML に直接 JSON として埋め込んでおり API を経由しないため、一部のフロントエンド<=>バックエンド間のデータフローを読み解くのに苦労したのですが、この辺りは今後の課題ですね。
(まさに絶賛対応中)

フロントエンド側の解析手順で有用な情報をお持ちの方は、ぜひコメントなどでお知らせいただきたいです！

まとめ

今回は新しい開発現場に参画した直後での、既存コードの解析の具体的な進め方についてご紹介しました。

今後の日本では副業採用が進むなど、人材の流動性がさらに高まっていくと予想されています。
つまり、エンジニアが新しいシステムに触れる機会もまた相対的に増加していく、ということです。
そういった場面で、本記事が少しでもお役に立つことができれば幸いです。