プロジェクトにおけるドキュメント

dev

syanpeiさんのコメントから色々考えてみました。
確かに「コードの方が雄弁」ってのは言い過ぎたと思います。失礼しました。コードだけじゃ分からないことって沢山ありますもんね。

システムが小規模で単純なものじゃない限り、設計モデルを作った人以外、モデルの全体像をコードだけ読んで理解するというのは、難しく時間のかかることです。でかいシステムをコードだけで把握してくれと言われたら辛いですが、その時に自分がやることは、おそらく次のようなことです。

  • RDBからリバースしたモデルから把握しようとする。
  • ソースコードなどからアプリケーションをリバースできるなら、それを利用する。おそらく関連が集まっているクラスが重要だと当たりをつける。
  • サイズの大きなファイルはきっと重要だろうと踏んで、ざっと目を通す。

最初にやるべきことはやはり全体を把握することなので、もし全体像を表すモデルがあるのならそれをまず読みます。もしそれがなかったら、中心となるクラスにあたりをつけて芋づる式にコードを読んでいくしかないでしょう。


以前はテストの作業を手順書としておこし、一つ一つ手作業で行う必要がありましたが、Seleniumなどの自動テスト用のツールを使うことである程度自動で行うことができ、システムは何が出来るべきかという点を文書で書くよりも正確に示すことができます。もちろん、すべてのテストをツールで行うというのは、現実的ではないと思います。でも機械的にテストできる範囲が増える方が、チームにとって嬉しいことが増えると思うのです。そういったことから「以前よりコードが雄弁になってきた」と思ったのですが、雄弁と言うより緻密と言った方が良かったですね。


自動テストのコードは、テスト対象の振る舞いを正確に記述することが出来ますが、全体像を表現するには向いていません。将来、テストあるいは実行できるなにかで、システムの概要を表現できるようになったらいいなーと思います。

でも実際どうするのか考えると、システムの概要って何だ？という疑問にぶち当たりました。多分、単に抽象的というのとは違うと思うのですが、とりあえず抽象度を機械的に判断できたら何とか・・・うーん。コードで書くことのできる抽象度は年々上がっているけど・・・ダメだ。アイディアなしっす。