前置き

知らないシステムのソースコードを読むのはすごく大変だという話

はじめに断っておきますが、この記事はソースコードを早く読むための手引ではありません。
自分の思考整理の為に書いています。

私はどんな順番でソースコードを読んでいたか

ここでは、ある機能の全体像を理解することを目的とする。

<前提>
参画したばかりでまだシステムの全容をほとんど理解していないとする

まず目的の機能にアクセスする入口または出口を探す
見つけたファイルを頭らか最後まで一通り読む。
呼び出している関数、または実行元に飛んで、またファイルを頭らか最後まで一通り読む。
3を繰り返す
機能の入口と出口が繋がったら全体を読んだことになる。

上記のやり方でコードを読むにあたってハマったポイント

フレームワークの理解が足りない
慣れていないフレームワークはどこに何があるかわかりません。
今回約３年ぶりにRailsを触りましたが、パラメーターどこで取得してるの？
routes.rbやcontrollerの存在も忘れているので、APIのエンドポイントもどこにあるかわかりませんでした。
言語の理解が足りない
約３年ぶりにRailsということでRubyも３年ぶりです。
ぱっと見ただの変数だと思ったのが実は関数でしたというのがよくありました。
アーキテクチャの理解が足りない
依存関係にある外部システム、インフラ構成について理解がない。どこでどんな処理をしているか知らない
目的ファイルの場所が分からない
一見して分からない繋がり
- API
- 外部API
- バッチ処理
- 常駐プログラム
- スレッド（非同期処理）
  上記のような要素が出てくると行き詰まることが多いです。互いに何らかの方法でやり取りをしているはずですが、それを突き止めないといけません。同一の変数名やクラス名が出てくるならgrep検索で関連場所を見つけられるかもしれません。
  スレッドは何のライブラリを使っているかわからないと呼び出し元さえ特定できません。
分からないデータ構造
悪名高い〇〇_jsonのようなjsonオブジェクトを直接扱っている変数の中身が分からない。
Rubyに関しては型が無いので、引数を見てもどんなパラメータを受け取っているかわからず
統一されていない命名規則
Vue2を使っていて、コンポーネント名の定義場所と利用箇所で命名規則が違う箇所がありました。違いはパスカルケースかケバブケースかなので変換すればgrep検索で探せますがひと手間で時間がかかります。静的解析が正しく機能していないのもつらいです。
読む必要がない箇所を読んで時間を取ってしまう

これからやっていけそうな対策を考える

わかる人に聞くやコードをリファクタリングして品質を保つと言うのは日頃からさんざん言われている自明なことなので、ここではそれ以外のことを考えてみたい

こんな素晴らしい記事を発見

ソースコードを読むための技術(チートシート)

自分のコードの読み方の悪いところ

まず目的の機能にアクセスする入口または出口を探す ← ここに時間がかかる
見つけたファイルを頭らか最後まで一通り読む ← ここに時間がかかる
呼び出している関数、または実行元に飛んで、またファイルを頭らか最後まで一通り読む ← ここに時間がかかる
3を繰り返す
機能の入口と出口が繋がったら全体を読んだことになる。

「目的の機能にアクセスする入口または出口を探す」に時間をかけてしまっている原因

アーキテクチャの理解が足りない
フレームワークの理解が足りない
言語の理解が足りない
目的ファイルの場所が分からない

<対策>

システムのドキュメントを読む
言語やフレームワークについては各ツールのドキュメントを片手に読む
チュートリアルを先にやってみるのも良いかも
はじめにプロジェクトのディレクトリ構造を読んで見る

「見つけたファイルを頭らか最後まで一通り読む」に時間をかけてしまっている原因

一見して分からない繋がり
分からないデータ構造
統一されていない命名規則
読む必要がない箇所を読んで時間を取ってしまう

<対策>

システムのOpenAPI等のより実装寄りのドキュメントを読む
ファイル名、関数名等から役割を判断する
コメントを読む
先にデータ構造を確認する
インターフェースを把握する

コードを読む時の心持ち『コードを読んではならない』

私の場合コードを読むときに手当たり次第にソースファイルを上から下まで全部見るとやってしまいがち…

コードを読むときにどこに注目するべきか？

名前（ディレクトリ名、ファイル名、クラス名、関数名、引数名、変数名）
コメント
データ構造
ドキュメント