« 抗原テスト | メイン | 年度初め »

2005年3月28日

コード=ドキュメント

カテゴリー: [プログラミング]

私は,コードを読みやすく書くことを常に心がけます.最初はいい加減に書いても,必ず,徐々に整理していきます.どんなにドキュメントを詳しく書いても,結局,コードが一番正確で詳しいと思っているからです.

ドキュメントをいっさい用意しないで,コード読め,っていうのは,もちろん勘違いですが,コードよりも,いろいろなドキュメントを書く方に注力するのは,大事なところを間違えていると思います.
ちなみに,私が書くドキュメントというのは,Javadocのように自動生成されたドキュメントとその補足,ユーザ向けの使用方法などです.ソフトウェアの種類や,その設計の内容によっては,設計の概略についてドキュメントも書きます.ただ,設計について詳しく書けば書くほど,コードが変わったときに,ドキュメントを追従させるコストが発生するので,一定以上に詳しくは書きません.

ただ,こういうことを誤解を招かずに説明するのは非常に大変です.その点,この文章は,非常にわかりやすいです.
ソフトウェア系の人には有名な Fowler さんの文章の日本語訳です.

Martin Fowler's Bliki in Japanese - コードがドキュメントだ

無駄なドキュメントというのは,結局読まない(読まなくても問題ない)ドキュメントや,読んでも意味が分からないドキュメントですね.
あとは,古くなって最新コードと一致していないドキュメントなんかは,害の方が大きいです.
こういう無駄なドキュメントというのは,結構あるようです.

詳細な実装なんかはコードを読めばわかるのですから,ドキュメントには,コードを読んでもわからないような,設計の大枠とか,設計方針とか,そういうものを書いておくべきものだと思います.
コードがあれば,自動で生成できるものについて,手で詳細なドキュメントを書くのも変な話です.
もちろん,設計過程でいろいろと書くものは別です.ただ,私はこれは,ドキュメントと言うよりメモだと思っていますが.

どこかで読んだ記憶があるものの受け売りですが,昔は計算機の環境が貧弱で,ソースをドキュメントとして使えるほどわかりやすく書くことができなかったので,フローチャート等のドキュメントが必要だったが,今はそういうことはなく,コードと重複するものを書く必要はないわけです.

ちなみに,フローチャートは,名前の通り,流れ(フロー)をもろに書ける(流れしか書けない)ので,構造化プログラミング以前のものですから,もう捨てるべきもののはずですが,未だに使っているところがあるそうなのです.この話を聞いたときには,ちょっとびっくりしましたね.あんまり,詳しくは書けませんが.
それが役に立つのかと言えば,きっとそんなことはないのです.結構な残業代を使って書いているんだろうなあ,と思います.

投稿者 shingo : 2005年3月28日 20:28

トラックバック

このエントリーのトラックバックURL:
http://isolinear.info/cgi-bin/mt/mt-tb.cgi/70

コメント

コメントしてください

コメントスパム等の対策のために,大量のURLを含むコメント,古いエントリーに対するコメント,連続したコメントなどは,一旦保留されます.




保存しますか?