ここ3日間ほど、家で山にこもって一人ソースコード読み大会みたいなことをしていた。Perlのコードについては、だいたい以下のような手順が最も読みやすいことがわかった。
1. Foo.pmのPODの上の方をよむ
2. Fooについてのblog記事などを検索して、そのモジュールが解決しようとしている問題について理解する
3. Foo.pmの中身を読んでいく
いきなり1 -> 3といくのと、2を挟むのとで大分効率が違う。2があると、「このモジュール全体の目的はこうなので、この部分はきっとこういうことをするのだろう」という風に部分部分のコードの意図を推測しやすくなるので。
ということを含めても、やっぱり「このモジュールはどういう問題を解決しようとしているのか」ということが何らかの形でドキュメントされていることはすごく大事なのだなあ、と思いました。まる。
プレゼンとかブログの記事にもおそらく形式があって、問題意識からスタートすると
1. こういう問題があります
2. 既存の解決策としてこれこれやあれあれがあります
3. 上記の解決策では満たせない条件Xを満たせるMをつくりました
という書き方になると思うんだけど、これを地でいきすぎるとちょっともったいぶった感じになるので、
1. Mをつくりました
2. Mは全体としてこういう問題を解決します
3. 既存の解決策として(ry
4. Mは、上記の解決策では満たせない条件Xを満たせます
という方がカジュアルな気がした。どちらの場合も問題意識がはっきり表現されていると分かりやすい。
