アカウント名:
パスワード:
微細に書かせるから書きたくなくなるんだよ。
# ドキュメント?欲しけりゃくれてやる# 俺の全てをソースに置いてきた
ソースちゅうのはミクロな視点なので、マクロな視点の読み物は別途あると便利ですよね。各モジュールの目指す役割など、つーかどのソースをまずあたればいいのかがわかるものが、ざっとでも書いてあるとうれしい。あと当初の考えが甘くて苦労したポイントなどが書いてあるとそれだけでもそこが要注意だとわかる。
ソースは結論しか書いてないからその経緯がほしいんですよね何のためにわざわざこんな実装なのか、とかこれは何を意味する処理なのか、とか。ソースコメントは本人視点になりやすくドキュメントは第三者視点になりやすい。
倒産した会社のソースを引き継いだときに渇望したのは要件定義と倒産までの運用内容の経緯でした。ソースなんて読みゃわかるし。
そうなんですよね。マクロな視点が欲しいんです。なのになぜかExcelにコードを日本語に直したレベルの詳細なものを書いてからじゃないとコーディングさせてくれないプロジェクトが存在するんですよ。いらない詳細なドキュメントばっかで、どのモジュールが何をするものなのかつながりなんかの資料が存在しないひどいプロジェクトでした。
どうしてそんなことになっているかというと、そのドキュメントがあることで何らかの免責になる人がいるんでしょうね。
ドキュメントを作ったぞ、と。これに書いてあるじゃないかと。でも、そんなドキュメントが免責になるということは要求してる側はそのドキュメントを見ていない/理解していないということ。あるだけでいいという種類のものなんでしょうね。つまり無駄なもの。
免責にならないという事例を沢山つくらないと結局、改善しないのかもしれません。
実装詳細をいちいち微細に書かせてたんならそう言いたくなるのは当然だよね。もし詳細な仕様を書かされたと文句言ってるのなら首切って排除するのが上司の仕事だけど。
# 俺の全てをソースに置いてきたと言ってる所を見る限り怪しいけどこれだけでは判断できないな。
実装詳細を仕様書に書け仕様書に書けと上(主に一時請け)が口をすっぱくして言うので、最終的にソースをWordにコピペして変数名などを日本語に直した、という事態を何度も体験したことがあります。
詳細に書けはそういう事態を招くので、適切な粒度を指定しないと危ないです。 つーか、本当に詳細な設計書は製造レベルで考えないといけないので、それだったら製造したほうが早い→ソースを設計書にコピペ、という空気になりがち。 (特にスケジュールが押してて、仕様書が納品物だと。) そしてそんな設計書であれば、始めからソースを読んだ方が早いの
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
犯人はmoriwaka -- Anonymous Coward
簡潔に説明する文章だけならいいんだよ (スコア:1)
微細に書かせるから書きたくなくなるんだよ。
# ドキュメント?欲しけりゃくれてやる
# 俺の全てをソースに置いてきた
Re:簡潔に説明する文章だけならいいんだよ (スコア:1)
Re: (スコア:0)
ソースちゅうのはミクロな視点なので、マクロな視点の
読み物は別途あると便利ですよね。
各モジュールの目指す役割など、つーかどのソースをまず
あたればいいのかがわかるものが、ざっとでも書いてあると
うれしい。
あと当初の考えが甘くて苦労したポイントなどが書いてあると
それだけでもそこが要注意だとわかる。
Re:簡潔に説明する文章だけならいいんだよ (スコア:1)
ソースは結論しか書いてないからその経緯がほしいんですよね
何のためにわざわざこんな実装なのか、とか
これは何を意味する処理なのか、とか。
ソースコメントは本人視点になりやすくドキュメントは第三者視点になりやすい。
倒産した会社のソースを引き継いだときに渇望したのは
要件定義と倒産までの運用内容の経緯でした。
ソースなんて読みゃわかるし。
Re: (スコア:0)
そうなんですよね。
マクロな視点が欲しいんです。
なのになぜかExcelにコードを日本語に直したレベルの詳細なものを書いてからじゃないと
コーディングさせてくれないプロジェクトが存在するんですよ。
いらない詳細なドキュメントばっかで、どのモジュールが何をするものなのかつながりなんかの資料が存在しない
ひどいプロジェクトでした。
Re: (スコア:0)
どうしてそんなことになっているかというと、
そのドキュメントがあることで何らかの免責になる人がいるんでしょうね。
ドキュメントを作ったぞ、と。
これに書いてあるじゃないかと。
でも、そんなドキュメントが免責になるということは
要求してる側はそのドキュメントを見ていない/理解していないということ。
あるだけでいいという種類のものなんでしょうね。
つまり無駄なもの。
免責にならないという事例を沢山つくらないと
結局、改善しないのかもしれません。
Re: (スコア:0)
実装詳細をいちいち微細に書かせてたんならそう言いたくなるのは当然だよね。
もし詳細な仕様を書かされたと文句言ってるのなら首切って排除するのが上司の仕事だけど。
# 俺の全てをソースに置いてきた
と言ってる所を見る限り怪しいけどこれだけでは判断できないな。
Re: (スコア:0)
実装詳細を仕様書に書け仕様書に書けと上(主に一時請け)が口をすっぱくして言うので、最終的にソースをWordにコピペして変数名などを日本語に直した、という事態を何度も体験したことがあります。
詳細に書けはそういう事態を招くので、適切な粒度を指定しないと危ないです。
つーか、本当に詳細な設計書は製造レベルで考えないといけないので、それだったら製造したほうが早い→ソースを設計書にコピペ、という空気になりがち。
(特にスケジュールが押してて、仕様書が納品物だと。)
そしてそんな設計書であれば、始めからソースを読んだ方が早いの