アカウント名:
パスワード:
できあがったものの簡潔な説明は、確かにここで指摘されたように有用だと思う。けど、設計書にその役割を求めると、理想はともかくとして大概「格言」に引っ掛かることになるよね。
ろくでもないドキュメントの原因は書かせる人が、読む人間でも書く人でもないことだと思うんだ。
たとえばこんな雰囲気ですね。http://el.jibun.atmarkit.co.jp/pressenter/2012/02/7-9fcb.html [atmarkit.co.jp]http://el.jibun.atmarkit.co.jp/pressenter/2012/03/8-4118.html [atmarkit.co.jp]
こういう阿呆が実在すると、首を絞めて、切り落として、ミンチにして犬の餌にでもしたくなる。
文書を細かく正確に作る事が、後々混乱を防ぐ良い文書になる事もあるけど、まあ、これはねぇ。以前、Wordで作ったアンケートに□があって、該当する箇所を■に変更して提出した所、「レ点に描き直して」と言われた事があったけど。
テスト駆動を昇華すればいんじゃないの?そのうち、ドキュメントを書く⇒テストが自動生成される⇒そのテストを満たしたコードが生成される
ただ、コードとドキュメントが合っていても、両方とも間違っていることもある
いや、BDDはTDDと同じものだよ。正確には、TDDのテストコードとテストメッセージを自然言語(ただし英語)で書きやすくなるような工夫を加えることで、テストコードをテスト仕様書、テスト結果をテスト報告書として使えるようにしたもの。
こういう仕掛けを用意すると、コメントとコードが乖離するとプログラマに精神的負担がかかるため、コメントが偽物になりにくいという、淡い期待を抱いている流儀。
出来上がったもののを書くのは順番が逆です。ほぼ意味が無い。ドキュメントとして必要な部分を理解していれば、メンテナンスも困難ではありません。
問題になるとすれば ・必要以上のものを「必須記述項目」として管理しようとしている ・プロジェクト面メンバーの怠惰(後の事、他人のことを考慮しないモラルの低さ)ぐらいしかなく、それは必ずクリアする必要があるものです。
# 個人や超少人数なら、ほとんどドキュメントは不要かも・・・
> ・必要以上のものを「必須記述項目」として管理しようとしている
改版履歴および改変個所の明示
orz
設計書は設計書であり、例えばメンテとかに使うには「必要以上」のものが入らざるを得ないと思うんだけど。
コードのメンテナンスに限定するのなら、別に作ったドキュメントはあまり役に立ちませんよ。結局、そのドキュメントに書かれていることが正しいかどうかの確認のため、ソース解析を行うことになりますし。そんなものに工数をかけるなら、ソースコード上のコメントを増やしてもらった方が解析がはかどります。
システム全体のメンテナンスを行うのならそれは設計の範疇ですから、コードからおこしたドキュメントを使うなんてナンセンスですし。
そのコメントが正しいという保証は?
よく出来たドキュメントのあるプログラムは、プログラム自身がよく出来ているので、そのドキュメントは参照されないという・・・。不出来なプログラムには、ドキュメント自体が無い場合が多い。
同様の経験は確かにあるが、バグ発見に「も」役立つというだけで、そっちがメインじゃないよな。その目的のためだけにドキュメントを書かせるならS/N比が悪すぎる。# この文脈ではバグがSignal。要は時間をかけてコードを精査して埋もれたバグ発見しろや、だけど使った時間がもったいないからその分手を動かしてドキュメント残せ。
やっぱり最初から作りこまないのがベストで、そのためのKISS。プログラマにとって、適切なコメントが入ったシンプルなソースは詳細設計書に勝る。プログラムは設計書のとおりには動かないけれど、コーディングされているとおりには動く。
ここの問題はドキュメント作成にかかるコストが書かれていないし、効果についても定量的に書かれていない。どういったドキュメントをどのくらいの手間をかけて作成するべきかを明示して欲しいよね。
開発時の品質向上の効果についてはわからんが、開発後の保守を担当させられた経験上からは、肝心なドキュメントが足りなかったり、コードとの間に数箇所の違いがあるだけで、ドキュメントの正当性が怪しくなり、最終的にはソースを見ないと駄目という結論に・・・
ソース見れる奴はどうせドキュメントなんて見ないのさ(笑)
> プログラマにとって、適切なコメントが入ったシンプルなソースは詳細設計書に勝る。> プログラムは設計書のとおりには動かないけれど、コーディングされているとおりには動く。
全然関係ないことを並べて書かれてもなぁ。#プログラムはコメントの通りには動かないし、コメントがなくても動くものねぇ。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
人生unstable -- あるハッカー
前か後か (スコア:1)
できあがったものの簡潔な説明は、確かにここで指摘されたように有用だと思う。
けど、設計書にその役割を求めると、理想はともかくとして大概「格言」に引っ掛かることになるよね。
Re:前か後か (スコア:2)
ろくでもないドキュメントの原因は書かせる人が、読む人間でも書く人でもないことだと思うんだ。
Press Enter (スコア:2, 参考になる)
たとえばこんな雰囲気ですね。
http://el.jibun.atmarkit.co.jp/pressenter/2012/02/7-9fcb.html [atmarkit.co.jp]
http://el.jibun.atmarkit.co.jp/pressenter/2012/03/8-4118.html [atmarkit.co.jp]
こういう阿呆が実在すると、首を絞めて、切り落として、ミンチにして犬の餌にでもしたくなる。
Re: (スコア:0)
文書を細かく正確に作る事が、後々混乱を防ぐ良い文書になる事もあるけど、まあ、これはねぇ。
以前、Wordで作ったアンケートに□があって、該当する箇所を■に変更して提出した所、「レ点に描き直して」と言われた事があったけど。
Re:前か後か (スコア:1)
テスト駆動を昇華すればいんじゃないの?
そのうち、ドキュメントを書く⇒テストが自動生成される⇒そのテストを満たしたコードが生成される
ただ、コードとドキュメントが合っていても、両方とも間違っていることもある
Re:前か後か (スコア:1)
Re: (スコア:0)
いや、BDDはTDDと同じものだよ。
正確には、TDDのテストコードとテストメッセージを自然言語(ただし英語)で書きやすくなるような工夫を加えることで、
テストコードをテスト仕様書、テスト結果をテスト報告書として使えるようにしたもの。
こういう仕掛けを用意すると、コメントとコードが乖離するとプログラマに精神的負担がかかるため、
コメントが偽物になりにくいという、淡い期待を抱いている流儀。
Re: (スコア:0)
出来上がったもののを書くのは順番が逆です。ほぼ意味が無い。
ドキュメントとして必要な部分を理解していれば、メンテナンスも困難ではありません。
問題になるとすれば
・必要以上のものを「必須記述項目」として管理しようとしている
・プロジェクト面メンバーの怠惰(後の事、他人のことを考慮しないモラルの低さ)
ぐらいしかなく、それは必ずクリアする必要があるものです。
# 個人や超少人数なら、ほとんどドキュメントは不要かも・・・
Re: (スコア:0)
> ・必要以上のものを「必須記述項目」として管理しようとしている
改版履歴および改変個所の明示
orz
Re: (スコア:0)
設計書は設計書であり、例えばメンテとかに使うには「必要以上」のものが入らざるを得ないと思うんだけど。
Re: (スコア:0)
コードのメンテナンスに限定するのなら、別に作ったドキュメントはあまり役に立ちませんよ。
結局、そのドキュメントに書かれていることが正しいかどうかの確認のため、ソース解析を行うことになりますし。
そんなものに工数をかけるなら、ソースコード上のコメントを増やしてもらった方が解析がはかどります。
システム全体のメンテナンスを行うのならそれは設計の範疇ですから、コードからおこしたドキュメントを使うなんてナンセンスですし。
Re: (スコア:0)
そのコメントが正しいという保証は?
Re: (スコア:0)
それが正しいという保証なのか、間違ってるという保証なのかが人間には判然としないというだけで
Re: (スコア:0)
よく出来たドキュメントのあるプログラムは、プログラム自身が
よく出来ているので、そのドキュメントは参照されないという・・・。
不出来なプログラムには、ドキュメント自体が無い場合が多い。
Re: (スコア:0)
同様の経験は確かにあるが、バグ発見に「も」役立つというだけで、そっちがメインじゃないよな。
その目的のためだけにドキュメントを書かせるならS/N比が悪すぎる。
# この文脈ではバグがSignal。
要は時間をかけてコードを精査して埋もれたバグ発見しろや、だけど使った時間がもったいないから
その分手を動かしてドキュメント残せ。
やっぱり最初から作りこまないのがベストで、そのためのKISS。
プログラマにとって、適切なコメントが入ったシンプルなソースは詳細設計書に勝る。
プログラムは設計書のとおりには動かないけれど、コーディングされているとおりには動く。
Re: (スコア:0)
ここの問題はドキュメント作成にかかるコストが書かれていないし、効果についても定量的に書かれていない。
どういったドキュメントをどのくらいの手間をかけて作成するべきかを明示して欲しいよね。
開発時の品質向上の効果についてはわからんが、開発後の保守を担当させられた経験上からは、
肝心なドキュメントが足りなかったり、コードとの間に数箇所の違いがあるだけで、ドキュメントの正当性が怪しくなり、
最終的にはソースを見ないと駄目という結論に・・・
ソース見れる奴はどうせドキュメントなんて見ないのさ(笑)
Re: (スコア:0)
> プログラマにとって、適切なコメントが入ったシンプルなソースは詳細設計書に勝る。
> プログラムは設計書のとおりには動かないけれど、コーディングされているとおりには動く。
全然関係ないことを並べて書かれてもなぁ。
#プログラムはコメントの通りには動かないし、コメントがなくても動くものねぇ。