概要
コードリーディングにまつわるエトセトラ。
経緯
大量のレガシーコードを読むことになりそうなので、コードリーディングの知識を整理し、
自己の理解を深めるとともに、チームメンバーとの共有をすることになりました。
下準備
事情通の把握
該当コードに詳しい人物を把握しておく。
フレームワークの設計を理解する
フレームワークを利用している場合は、フレームワークの概念を理解し、
自分が担当する箇所がどのような役割をしているのか理解する。
ドキュメント
ドキュメントを読む
ドキュメントを読むことで、内部構造を理解する。
ただし、ドキュメントの質が低かったり、ソースコードとの同期の度合いなどによっては信頼度が下がる。
プロジェクトの事情通がいれば、ドキュメントがどの程度信頼できるか確認の上で活用度合いを決める。
高レベルの設計を把握する
信頼できるドキュメントに、システムの高レベルの設計がまとめられているなら事前に把握しておく。
全体的な構成を理解できていると、読む進めやすくなる。
プログラム
まずは高レベルの設計を把握する
信頼できるドキュメントがないなら、プログラムのエントリポイントから
初期化・本処理・終了処理など大枠の流れや構成を把握する。
この段階では詳細に立ち入りすぎないこと。
動かして確認する
動作を確認することで、内部の構造を深く理解する。
デバッガ、ログなどを活用する。
ライブラリの呼び出しを検証する
外部ライブラリを使っている場合、そのライブラリを呼び出しを検証する。
また、ライブラリのドキュメントを読む。
本番環境以外では、 外部ライブラリを利用できない場合などもあることから
シュミレータ・モックなどの存在を確認しておく。
キーワードを探す
例えば検索の処理を見たければ、 「search」 で grep し、該当ファイルを見つける。
ピンポイントで処理を確認したい場合に有効。
ただし、適切な命名がされていない場合は当てにならない。
補助的な手法
何かしら図を描く
処理の流れ、状態など複雑な部分に関しては図を書いておく。 清書はのちほど必要に応じてするので、自分が見て把握出来る程度の雑な図だけ残しておく。
ドメインの用語を書き留めておく
Markdown, マインドマップなど書き残す形式は問わないが、 コードリーディングの助けになりそうな用語は随時メモをとっておく。
ツールを活用する
静的言語
IDE を利用するとコードリーディングが捗る
- 呼び出し元メソッド参照
- 呼び出し先メソッド参照
- 継承リスト参照
- 基底クラス参照
- インターフェースの実装クラス参照
- オーバーライド元のメソッド参照
など。
動的言語
REPL を活用する。
Ruby なら pry (irb)。
UnitTest を書く
- 想定した理解が正しいかどうか検証できる。
コードにコメントを書く
- git などソースコード管理ツールにコードを保存し、コメントを追加しながら読む
- 理解とともにコメントは増やしていく
アノテーションコメントを残す
- 解決すべき課題、確認すべき仕様、改善すべき箇所などは
# TODO:など、アノテーションコメントを残す
Ruby のアノテーションコメントについては、下記リンク先を参照。
Ruby | アノテーションコメント（TODO、FIXME、OPTIMIZE、HACK、REVIEW）
コードフォーマッタで体裁を整える
コードの体裁が整っていないために読み難くくなっている場合は、コードフォーマッタ等で体裁を整える。
リファクタリングする
- リファクタリングし、より読みやすい形にしていく
- ただし、プログラムを壊していないか確認する必要があるので UnitTest の作成とセットで行う必要がある
覚書を残す
設計不備や気になったことなど、アノテーションコメントでは残せないようなことや システムの事情通に確認したいことを箇条書きレベルで覚書を残しておく。
これが改修の際の TODO になる可能性が高い。
仕上げ
事情通のレビュー
事前に作成した覚書を元に、事情通に内容を確認する。 ここで不明点を明らかにしたり、自分の理解が間違っていいないか確認する。
人に説明する
説明できるなら理解は深まっている。 必要に応じて説明のための資料をまとめる。
整理する
コードリーディングの結果、今後の開発・運用のためにまとめておくべき内容があるならドキュメントにまとめて残す。 組織により、 esa や Qiita:Team などのナレッジマネジメントツールだったり、 Word・Excel だったりするだろう。 この際に、事前に作成しておいた図やドメインの用語を役立てる。
