2009/03/24
コードと別にドキュメントを書く意味
昨日の続き。
異なる意味や構造を持つ2つの言語で同じことを書くと相補的に文章の正確さを高めることができるということだ。ソフトウェア開発の各段階で、コーディング言語以外にいろいろな言語を使うことの意義はそこにある。
私がコードと同時にドキュメントを重視するもうひとつの理由がこれだ。
コードは動かなければ意味が無い。動かすには、実装の詳細に気を配らないとならない。 設計上は「どちらでも良い」選択肢があったとしても、動くコードにするためには どちらかを選ばないとならない。そうやってとにかく具体的に、末端まで目を配っていると、 大局的、抽象的な視点を忘れがちになる。 そこで、実装の詳細の迷路に足を取られて大局的な方向があやふやになってきた あたりでドキュメントを書いてみると、ふっと全体の見通しが良くなったり、 実装の抜けを発見できたりする。あるいはそもそも「ドキュメントがうまく書けない」 ことから、自分が問題をちゃんと理解していないことに気づいたりする。
あるいはこういう考え方もできる。実現したい「何か」は空間上の一点だ。 それを通る直線が無数にあるように、実装も無数にあり得る。たまたま ある実装を選んだとする。ところが、後からその実装を見た人には、 どこが本当に通りたかった点なのかがわからない。ここでドキュメントという もう一本別の直線があれば、その交点として、設計者の意図を明確に 示すことができる。
(ソースコード内にドキュメントを埋め込むのを私が好まないのは、 ひとつにはこれが理由だ。 コードを書くモードと同じモードでドキュメントを書くと、 直線はほとんど重なってしまい、交点を明確に示せない。 プトロコルとか暗号アルゴリズムの仕様を詰めるときに、その仕様に 基づいた複数の実装を独立して開発してみるように、 コードとドキュメントは別の出発点から書いた方が、 より相補的に価値を高めることができると思う。)
Tag: Programming
