やる気がストロングZERO

やる気のストロングスタイル

OSSコードリーディングをスムーズに進めるためのメモ

OSSのコードリーディングをしてみる中で、内容を把握するためにして良かったと思った事をメモっておく。

リーディング対象にしたもの: github.com ※主にはfilebeat

リーディングが上手く進まないパターン

詳細を追ってしまい帰ってこれなくなる

僕は不明点があると気になってしまい調べ始めて帰ってこれなくなる傾向がある。

例えば調査対象関数の引数に関数の返り値が使われていて、その関数を見に行ってその先でも更に不明な関数があって、、帰ってこれなくなる。(※全然気にせず読める人もいるようだ。人によるっぽい)

大体の場合、全体の感じを理解できていない状態でのこういった詳細の理解は難しく、使う時間に対してのリターンは少なく、気力だけが消費されて読むのを諦めてしまう。

内容把握を推し進めるために

ドキュメントを読む

OSSであればContributingなど、開発参加に際してのdocumentがあるのでざっくり読む。
開発環境の構築方法や構成についての説明があったりする。
たぶん質問フォーラムとかもあってこれもざっくり見たほうが良い(今回はあまり見てない。。)

読む対象を絞り、それ以外は意図的に無視する

具体的なイメージがしやすい部分を読む対象とし、それ以外は意図的に読まないようにする。
読むための気力が有限資源であることを強く意識し、目的以外の行動は極力しないようにする。

今回の場合は、filebeatが「ファイルを読み取る部分」を読みに行った。
どこかで対象ファイルをconfigファイルから特定して読み込む部分があるはずだと探した。

パーツ感を把握する

OSSだと大体いい感じに粗結合なモジュール化をされていることを期待して、全体のパーツ感を把握する。
パーツ感が把握できれば、読む対象パーツ以外を一気に無視できるようになる。

今回の場合、パーツ感はmain.goに書かれているコメントで把握できた。
https://github.com/elastic/beats/blob/master/filebeat/main.go

input, harvesterモジュールが今回の読む対象っぽい

// The basic model of execution:
// - input: finds files in paths/globs to harvest, starts harvesters
// - harvester: reads a file, sends events to the spooler
// - spooler: buffers events until ready to flush to the publisher
// - publisher: writes to the network, notifies registrar
// - registrar: records positions of files read
// Finally, input uses the registrar information, on restart, to
// determine where in each file to restart a harvester.

パーツ感がわかってくると、ディレクトリ構造に構造がなんとなく見えてきた。
使われている名前と概念が少しづつわかってきた。(扱うデータをeventという単位で表している等)

パーツ単位で動きがイメージできるようになれば「どのように使われているか」を起点にして理解範囲を広げていける

手元で動作できるようにする

ある程度読んで少しわかってきたら意図通りに処理が流れるか実際に動かして確認してみる。
動作テスト用にlocalで動作環境を用意するための方法が用意されていたりする。
今回は、Makefileを漁っていたら

testing/environments

に環境があることがわかり、コメントを読んで理解できた。
もしかしたらフォーラムとかに詳しく情報があったりするのかも。

まとめ

  • 読む範囲をとにかく絞る。わかった部分から徐々に理解を広げる。
  • ドキュメント・コメントを読む。コードから逆解析をするよりも効率がいい。
  • コードの詳細を理解しようとしない。必要になったときに初めて深く見るようにする。
  • 内容を覚えようとしない、読んで意図がわかったら次々行くほうが効率が良い。忘れたらまた読む。