バグ修正や新規機能追加の際にコードリーディングを行って必要な情報を集めたり、ソースコードへの理解を深めたりするわけですが、みなさんは最初からソースコードを読みに行くでしょうか？それとも何か参考となるドキュメントを先に読んでからコードリーディングに着手しているでしょうか？
ソースコードだけで知りたい情報を手に入れることは可能ではありますが、かんたんとは言い難いです。いつも10数行のコードを読むだけで必要な情報が手に入るのならば、どんなにありがたいでしょうか？できるだけ楽して理解を深めていくために、コードリーディングの補助としてドキュメントを読むメリットや立ちはだかる問題点、その改善方法について紹介します。
コードリーディングとともにドキュメントを読むことのメリット
そもそもコードリーディングはソフトウェアを理解するために行うものです。大まかな構造や一つ一つの処理の手順について、実装されたコードを読み解くことで理解していきます。一方でドキュメントはソフトウェアを理解しやすくするための説明資料として作成されますので、 コードリーディングとドキュメントは、「ソフトウェアを理解する」という共通の目的を持っている と言えます。そうなのであれば、コードリーディングの際にドキュメントを利用しない手はありません。
コードリーディングという骨の折れる作業の前にドキュメントを読んだり、コードリーディング中に行き詰まった際にドキュメントを確認したりすることは、ソフトウェアを理解するために大変有効な手段です。コードリーディングとともにドキュメントを読むことの主なメリットは以下の3点です。
- 理解しやすくなる
- 理解するまでの時間を短縮できる
- 誤った理解や勘違いを避けることができる
「できるだけ正確に手早くソフトウェアを理解する」という目的のために、コードリーディングの補助として積極的にドキュメントを活用しましょう。
どんなドキュメントや資料があるか？
コードリーディングと一緒に読んだり確認したりするドキュメントまたは資料としては、
- ソースコード内のコメント
- README
- 公式ドキュメント
- 要求仕様書
あたりが手に入れやすいでしょう。ほかにも
- 技術仕様書、Design Docs
- UMLの各種図面
- 手書き等も含めたかんたんなアーキテクチャ図やER図のような関係図
- 過去のメール、SlackやDiscordの書き込み
などもコードリーディングの際にヒントを得るためのドキュメントまたは資料となります。すべてがいつも揃っているわけではなく、またソースコードの実装を説明するために用意されたものでないかもしれませんが、コードリーディングという面倒な作業を少しでも楽にするために活用したいところです。
これらのドキュメントや資料には日常的に触れていると思います。しかし、コードリーディングのために READMEを読んでいるかと言われると、自信を持って「はい」と答えにくいのではないでしょうか。ソースコード内に記載されているコメントさえ読み飛ばしていることも少なくありません。
なぜメリットがあるのにコードリーディングの際にドキュメントを読まないのか？
では、ソフトウェアの理解の助けになるとわかっているのに、なぜコードリーディングの際にドキュメントを読まないのでしょうか？それはドキュメントの側にも問題があるからです。
- コードより優先して読む価値があるかどうか判断しにくい（信頼度が低い）
- あらゆる場面で都合よくREADMEが用意されていたり、的確なコメントが記載されていたりするわけではない（可用性が低い）
特に前者は、経験則から大抵の場合ドキュメントの質は低いと感じてきたため、読む価値がないと判断しているのではないでしょうか？
また、これらの問題以外にもドキュメントを読まなくなってしまう要因はありそうです。例えば、バグ修正などを行う場合はエラーメッセージを見て、エラー発生箇所を見に行くという手順で解析を進めるため、ドキュメントを読む工程の入る余地がありません。さらにコードリーディングを始めてしまうと、あまりにもコードリーディングの負担が大きく、ソースコードに集中することで精一杯となるため、一度目先を変えてドキュメントを確認しようという発想に思い至らないことも多々あります。
こうしたドキュメント側の抱える問題やコードリーディングを行う際の手順およびコードリーディングという作業の困難さに起因した理由でドキュメントを読まないことが習慣化してしまうのかもしれません。
コードリーディングとともにドキュメントを確認していくために
ドキュメントを読まなくなった習慣を少しずつ改善していくためにかんたんなことから始めてみましょう。
前述したとおり、普段から他人の書いたコメントの質に悩まされているからコメントは読まないと決めてしまっているかもしれません。しかしOSSのREADMEやコメントのように、多くのプログラマの目に触れてきたドキュメントは、コードの質と同様に信頼できる傾向にあります。せめて OSSのREADMEやコメントは読む という習慣をつけるところから始めてみてはいかがでしょうか？
コードリーディングだけで理解しようとして行き詰まってしまったとき、
- いろんなファイルからコメントだけをかいつまんで読む
- READMEの関連部分に戻って読み返す
- 公式サイト、公式ドキュメントを調べてみる
というような基本情報に立ち返る癖をつけましょう。最初は自然にできないかもしれません。そういうときは、行き詰まった際に「何かヒントはないかな？」と ソースコード以外の場所にヒントを求めるようにする と良いでしょう。実のところ、行き詰まったら詳しい人に聞くという方法はよく使っているのではないでしょうか。そこにドキュメントを確認するという選択肢も加えてみてください。
また、十分なドキュメントが手に入らないときの実践的で手軽な手法として、ファイル内、クラス内で定義されている関数一覧表や変数・定数一覧表を自分で作るというやり方もあります。関数名や変数名には機能の説明の一部が反映されているため、それらを並べて見比べるだけでも非常に有益な情報が手に入ります。コードリーディングによる理解を進めるために、コードリーディングの手を止めて自分で資料を作るというと違和感があるかもしれませんが、「できるだけ正確に手早くソフトウェアを理解する」という目的に照らし合わせてみれば、急がば回れ的な手法であり、試してみる価値はあります。
こうしたソースコード以外のドキュメントに頼る習慣を身につけることでコードリーディングへの負担を軽くし、「できるだけ正確に手早くソフトウェアを理解する」という目的を達成できるようになるでしょう。
まとめ
コードリーディングの補助としてのドキュメントの活用について説明しました。コードリーディングと一緒にドキュメントの確認も行うことで「できるだけ正確に手早くソフトウェアを理解する」ことができます。これまでの経験則からドキュメントの確認を億劫に思う習慣が身についている人も少なくないかもしれませんが、頭の片隅に「ドキュメントを調べてみれば何かヒントがあるのでは？」という選択肢が浮かんでくることで行き詰まりを解消することができ、コードリーディングへのストレスや苦手意識をも和らげてくれるはずです。ぜひコードリーディングの補助としてドキュメントも読むという習慣をつけていきましょう。