アカウント名:
パスワード:
ここでドキュメントは要らないって言ってる人達はソース中にコメントも書かない人なんだろうか。
コメントを書くのだって同じ内容を別の言語で重複して記述することに違いないと思うんだけど。
もしコメントを書いてるんだったら、それと同じ理由でドキュメントを書く価値があるんじゃないの?
ここにぶら下げる意味はあんまりないですが、コメントつながりで。
私が感銘を受けたコメント の書き方。 ここ [aid.her.jp]の 11.1.c を見てね
まあ、コメントはバージョン管理システムの範疇だから手続き的には楽ちんなんだけどね。
「自社のプロダクトをバージョン管理を通じて日々育ててライフタイムの間面倒見る」なんて状況で仕事してる人は「仕様書(設計書)を変更に追従させる」のはほぼ無理ゲーなんじゃないのかな。三社ほどそういう状況で仕事したけど、仕様書(設計書)を見たことがない。バージョン管理とバグ報告と適切なリグレッションテストで開発効率を下げないでうまく廻るように工夫してるんだと思うけど。
>ここでドキュメントは要らないって言ってる人達はソース中にコメントも書かない人なんだろうか。
逆、逆。ソース中にコメント等で書いてあるから、(同じことを書いた)設計書はいらないと言っている。
拡大解釈して「ソース中にあらゆることが書いてあるからソース以外のドキュメントは一切不要」と思っている人も中にはいるかもしれないけれど、多くの人はソースだけで示せないことについて別立てでドキュメントを作ることは否定していないと思う。
それならコメントをなくしてドキュメントとしてまとめた方がいいかもよ?処理の概要や背景を書く場合、思いつきで散発的に書かれたコメントよりはドキュメントとしてまとめた方が説明しやすいだろうし。
メンテナンス性に関してはコメントも途中で整合性なくなるのはよくあることなのでドキュメントと対して変わらないと思うよ。
1)「いわゆるドキュメントにまとめる」:図を駆使したりおそらく表現力は豊か。でもメンテは控えめに言って大変。はっきり言えば悪夢。
2)「イシュー追跡システムにまとめる」:ツールが整備されてるのでたぶんメンテは楽。手続きとして開発作業に組み込まれるのでメンテ放棄の状態にはなりにくい。お客に出すなら別途作業が必要。
で、1)か2)のどちらを選ぶかが分かれ目になるんじゃないかな。ちなみに自分は2)。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
Stay hungry, Stay foolish. -- Steven Paul Jobs
コメントも書かない? (スコア:0)
ここでドキュメントは要らないって言ってる人達はソース中にコメントも書かない人なんだろうか。
コメントを書くのだって同じ内容を別の言語で重複して記述することに違いないと思うんだけど。
もしコメントを書いてるんだったら、それと同じ理由でドキュメントを書く価値があるんじゃないの?
Re:コメントも書かない? (スコア:1)
ここにぶら下げる意味はあんまりないですが、コメントつながりで。
私が感銘を受けたコメント の書き方。
ここ [aid.her.jp]の 11.1.c を見てね
Re: (スコア:0)
まあ、コメントはバージョン管理システムの範疇だから
手続き的には楽ちんなんだけどね。
「自社のプロダクトをバージョン管理を通じて日々育てて
ライフタイムの間面倒見る」なんて状況で仕事してる人は
「仕様書(設計書)を変更に追従させる」のはほぼ無理ゲー
なんじゃないのかな。
三社ほどそういう状況で仕事したけど、仕様書(設計書)を
見たことがない。
バージョン管理とバグ報告と適切なリグレッションテストで
開発効率を下げないでうまく廻るように工夫してるんだと思うけど。
Re: (スコア:0)
>ここでドキュメントは要らないって言ってる人達はソース中にコメントも書かない人なんだろうか。
逆、逆。
ソース中にコメント等で書いてあるから、(同じことを書いた)設計書はいらないと言っている。
拡大解釈して「ソース中にあらゆることが書いてあるからソース以外のドキュメントは一切不要」と
思っている人も中にはいるかもしれないけれど、多くの人はソースだけで示せないことについて
別立てでドキュメントを作ることは否定していないと思う。
Re: (スコア:0)
それならコメントをなくしてドキュメントとしてまとめた方がいいかもよ?
処理の概要や背景を書く場合、思いつきで散発的に書かれたコメントよりはドキュメントとしてまとめた方が説明しやすいだろうし。
メンテナンス性に関してはコメントも途中で整合性なくなるのはよくあることなのでドキュメントと対して変わらないと思うよ。
Re: (スコア:0)
1)「いわゆるドキュメントにまとめる」:
図を駆使したりおそらく表現力は豊か。でもメンテは控えめに言って大変。はっきり言えば悪夢。
2)「イシュー追跡システムにまとめる」:
ツールが整備されてるのでたぶんメンテは楽。手続きとして開発作業に組み込まれるのでメンテ放棄の状態にはなりにくい。お客に出すなら別途作業が必要。
で、1)か2)のどちらを選ぶかが分かれ目になるんじゃないかな。
ちなみに自分は2)。