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
コメント
スーパーコピー時計専売店
当店は海外安心と信頼のスーパーコピーブライトリング、代引き店です.
正規品と同等品質のシャネル コピー代引き,品質が秀逸,値段が激安！
ブライトリングコピー,代引きなどの商品や情報が満載！
全商品写真は100%実物撮影です!
お客様の満足度は業界No.1です！
スーパーコピー時計,時計コピー ,ブランド時計コピー販売(n級品)店舗 ブランド腕時計(ロレックス,ブライトリング,タグホイヤー,オメガ,ガガミラノなど)の最新 情報やイベントを紹介する正規販売店と腕時計コピーの専門サイトです。
当店はロレックスやパテックフィリップなどの新品スーパーコピー時計の販売と。
ルイ ヴィトン 長財布 激安 https://www.b2tokei.com/product/detail.aspx?id=5395
投稿者 ルイ ヴィトン 長財布 激安 : 2023年11月10日 20:35