アカウント名:
パスワード:
DB設計書とか通信インタフェースとかUIとか色々ありますからね。ソースコードのコメントで表現が難しい/できなのも多いのでは。
> しかし、自動出力したドキュメントは「上司がわからないから」として却下された。
これもメソッドやクラスの(javadoc的な)物であればコードに触れない層にわからないだろうし、もっと上流の業務寄りな文書って必要だと思う。
＞もっと上流の業務寄りな文書って必要だと思う。
ほんとこれ。「後から他人がサポートやメンテするときには実はほとんどコメントや自動作成ドキュメントなんてやくに立たない」
なぜなら「何をしているか」は分かっても「何をしたいか（したかったか）」がわからないから。
極端に抽象化した話、X+Ｙ =Bしているのがわかっても、Xがなんなのか（リンゴなのか、速度なのか）、Bは何かわからなければドキュメントの意味がない。もっと言えば、Bがなにかわかっても「なんのためにBが必要で、システム全体の目的はなにで、Bはそのうちどういうものか」
これがわからんと意味がない。逆にこれさえわかれば、中身何ぞある程度自明だし、返るべき値がわかるから、デバッグするべきクラスや関数も自明になる。
たとえば状態Ａを、状態Ｂにするのが目的なアプリがあったとして、Ａ → Ｂソースコードに書かれてるのは → の具体的な方法。→ から Ａ や Ｂ を炙り出して推測しないといけないから、だから他人の書いたソースコードって読むのが難しいわけ。
自分で書いたソースコードなら暗黙に Ａ や Ｂ を頭に思い浮かべながらソースコード（→）を読めるけど、他人のソースコード（→）”だけ”を渡されたら、まず Ａ や Ｂ を → から炙り出して推測するという手間が必要となるわけ。その手間を軽減するためにコメントがあるわけで、または設計書や仕様書のような、とにかく Ａ や Ｂ を炙り出ししなくても知れる手段が用意されてるのは、有用なことだと思います。
だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。Ａ と Ｂ を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード（→）の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。そこのバランスの問題だと思うわ。
> Ａ と Ｂ を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード（→）の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。
それは書いた奴が無能なだけ駄目な仕様書の典型じゃんたまにいるよね、大昔の知識で止まってたり技術者としては並以下なのにソースコードやSQLを中途半端に書いてきて足枷ばかりはめようとするアホ
>だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。逆に、中身は邪魔です。仕様が網羅されているかを見るのに、コードに引っ張られて見てしまい、バグが有る時は作成者と同じ穴に嵌りがち。純粋に「A→B」が「何をしたいのか？」って点で表現されている物の方がずっと良い。
運用や運用支援をしている立場からの意見ですが。「本番環境で動かすもの」なら、設計書はほしいです。
トラブルが発生したとき、即時の対応が必要なときに、すべてのプログラムソースや設定ファイルを追って「問題を関係する箇所」を探している「時間的余裕」はありません。
設計書と事象から「問題に関係する箇所」を推定し、実行状況や入力データの不健全さを疑い、必要があれば「コードのバグ」を疑い、その箇所のプログラムソースを確認します。
コードのバグとして扱うのは、一番最後ですが、設計書がないなら「本番で不具合を起こした」ことから、「設計ミス」や「現実に則した動作をしないもの(バグを内包)」として、コードの納入元に即時の調査対応を求めることをエンドユーザーから求められます。
「コードを追う」までは、運用の契約に含まれていないことが多いのです。
運用や運用支援をしている身からすると、大変面倒だし、回復まで時間がかかるので、「本番環境で動かすもの」なら設計書をつけてほしいです。
ドキュメントが作られていても、「何をしたいか（したかったか）」が分からなければ意味は無いですよね。逆にコメントやソースや自動作成ドキュメントであっても、「何をしたいか（したかったか）」が判るようになっていれば問題無いですよね。正確には「コメントや自動作成ドキュメントなんてやくに立たない」ではなく「(ドキュメント作成能力にない人間による)ドキュメントやコメントや自動作成ドキュメントなんてやくに立たない」ではないでしょうか。自動生成で「何をしたいか（したかったか）」が出力されるよう書かれたソースなら全て解決。
「何をしたいか（したかったか）」
これは理論的にコメントや自動作成ドキュメントからは本質的に作成不可能なんですよ。
なぜか。
何かバグがあったとします。「何をしたいか、したかったか（要求、仕様、設計）」と「何をしているか(ソースコード)」が乖離しているからバグがあるわけです。結局出来上がるものは本来の「何がしたかったか」はわからないのです。
なので、自動作成ドキュメントでできたもの（だけ）なんて、メンテ時には役に立たないんですよ。ほとんどの場合。
うんうん。内容が理解できないと、形式しかケチをつけるところがないよね。
レビューで誤字脱字ばかりチェックしている自称有識者思い出した
意識高いってやつですか？
有識者＝意識が有ります。寝てません。という事なのだろう。
私には意識がありますと自称する存在に意識はあるかというのは難しい問題ですね。
元コメの指摘は全うだと思われるが･･･typoとか枝葉松葉は拘るとこじゃないかと。設計書はそういうのはすげー欲しいですよ。
＃ ソースコメントも、X + Y = B 的なコメントを書く人がなんと多いことか。＃ 「iに5を足す」が無駄なのは分かっても「listにIDを追加する」が同レベルなことには気づかないんですよねぇ･･･。
こういう揚げ足取りで足引っ張るしか能がない人がいなくなれば仕様書を書く時間が増えて全て解決するんだがなｗ
> こういう揚げ足取りで足引っ張るしか能がない人がいなくなれば> 仕様書を書く時間が増えて全て解決するんだがなｗ
設計書をまともに書く人は、指摘されて修正することに安心を感じるんだけど、
たまに設計書に指摘すると揚げ足取りで足引っ張るとかいう人いるよね？間違いを指摘するのがめんどくさくなる。
> 設計書をまともに書く人は、指摘されて修正することに安心を感じるんだけど、
しかし残念ながらここは投稿内容を修正できないスラドなのであった。正当な指摘であっても本筋に関係なければ議論の邪魔と斬り捨てられても仕方ないと思う。ここはそういう場だよ。
これはTypoの指摘や揚げ足取りじゃないだろ。たとえばIPｖ4の話をしている時に、アドレスの例として10.72.0.382とか言う奴がいたら、そいつの技術的見解や仕事の進め方についての発言に何の意味もない事はわかるだろう。十分に慣れ親しんでている人間なら気持ち悪さに耐えられないはずの事に気が付かないってことだから。そういう種類の間違いだと思うぞ。
> 10.72.0.38210.72.30.82 のtypoかもしれないし、間違う理由は人それぞれ。なのにたった一点を見て全体を判断する行為こそが愚かではなかろうか。
実際わたしの周囲にも、英語が苦手で、ディスクトップとかインストロールとかそういうレベルの単語を連発する人がいるが、その人のプログラムは群を抜いて優秀。その人のアウトプットのバグ率の低さは半端ない。でも毎年、新人は馬鹿にすんだな、その人を。すぐに認識を改めるけどさ。
＞でも毎年、新人は馬鹿にすんだな、その人を。すぐに認識を改めるけどさ。
その人のことをもっと知りたいのでもっと紹介いただける部分があったらぜひ書いていただきたいです。
それはプログラミング言語ではなくて英語というか外来語の話でしょ。しかも発音の話。まさかその人disktopとかinstrollとか書いたり打ったりするの？
十分に経験のある人であれば、代入先を右に書いたり、1オクテッドが255を越えるアドレスを書いたりなんて事は指が拒否するだろう。いつもやってることなんだからわざとじゃない限りそういう間違え方は出来ない。野球経験者にバットを握らせたとき、どんなに慌てていてもどっちの手が上になるか間違えるなんて事はあり得ないのと同じ、
「綴りが正しいか」も「英語というか外来語の話」の一例に過ぎませんし、間違っててもそれは本質ではない、と思いますよ。IPアドレスだと無効な入力として「999.999.999.999」と設定するUIもたまに見るし、指が拒否するレベルかなぁ…？
APIの名前の綴りとか、実際に使用する値として不正値入れてたらそりゃダメだけど、単語自体が可読性以上の意味を持たない部分でのtypoや、例である事が明確な文脈での不正値も本質とは無関係だしどうでもいいでしょう。
ところで私は8ビットの単位をオクテットって覚えてるんですけど、オクテッ「ド」が正しいんですかね？
# あと代入先が右って言語や環境は主流ではないけど普通にありますよ。# 有名所だとアセンブラのAT&Tシンタックス。代入先などが右に来る。超キモい。
ね、気になるでしょう？octetをどう読んでも「ド」の音は出てきませんからね。
これだな。ソース読めば詳細はわかるけど、全体が見えない（見えるまで時間がかかる）全体像、設計思想、設計の意図、データフロー、業務フロー、入出力設計書、データ定義書ぐらいは必要。逆に、下流の「プログラム設計書」とか、正直いらんと思う。
#ソースコードとプログラム設計書（ソースコードと1対1に対応）渡されて、引き継ぎ終わり言われてもねぇ・・・
DB 設計書って言っても、Excel の表にフィールド並べて1行コメントしてあるだけってレベルの多いしそのレベルで問題ないなら SQL にコメント入れとけば十分だって
そういうのは普通テーブルデザイナーツール使ってSQLとテーブル仕様書を自動生成するとコメントつきのSQLとExcelと生成してくれるでしょ
一番書きたいcreate tableなんて、管理しているソースではカンマで複数行にしているけど、丸括弧の中は一行で、マイナスマイナスから始まる行コメントを書くとエラーなのでは？
どう書けば良いのでしょう？
ソースコードのコメントを抜いて、COMMENT を追加するスクリプト通せばいいだけじゃない？
少なくとも PostgreSQL、SQLite3 に関しては-- は C/C++ で言うところの行末までの1行コメント // なので
---------------------------------------create table hoge (id text, -- user idpw text -- user password);---------------------------------------
のような書き方は出来ますよ。
> もっと上流の業務寄りな文書って
マニュアルという形で作ることはありますね。ユーザーにわかる内容、機能の目的などを記載。ユーザー目線になると違った操作感を見つけたりするので良い見直し材料になります。設計書よりは見てもらう可能性が高いような気もする(ユーザーは基本的にマニュアルなんて見ませんが、ごく稀に見てくれる方もいるのです。)
見直しのレベル感が個人の力量に依ってしまうのが難点ですが。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
物事のやり方は一つではない -- Perlな人
設計書と一言で言っても (スコア:3, 興味深い)
DB設計書とか通信インタフェースとかUIとか色々ありますからね。ソースコードのコメントで表現が難しい/できなのも多いのでは。
> しかし、自動出力したドキュメントは「上司がわからないから」として却下された。
これもメソッドやクラスの(javadoc的な)物であればコードに触れない層にわからないだろうし、もっと上流の業務寄りな文書って必要だと思う。
Re:設計書と一言で言っても (スコア:5, すばらしい洞察)
＞もっと上流の業務寄りな文書って必要だと思う。
ほんとこれ。
「後から他人がサポートやメンテするときには実はほとんどコメントや自動作成ドキュメントなんてやくに立たない」
なぜなら「何をしているか」は分かっても「何をしたいか（したかったか）」がわからないから。
極端に抽象化した話、
X+Ｙ =B
しているのがわかっても、Xがなんなのか（リンゴなのか、速度なのか）、Bは何かわからなければドキュメントの意味がない。
もっと言えば、Bがなにかわかっても「なんのためにBが必要で、システム全体の目的はなにで、Bはそのうちどういうものか」
これがわからんと意味がない。
逆にこれさえわかれば、中身何ぞある程度自明だし、返るべき値がわかるから、デバッグするべきクラスや関数も自明になる。
Re:設計書と一言で言っても (スコア:2)
たとえば状態Ａを、状態Ｂにするのが目的なアプリがあったとして、
Ａ → Ｂ
ソースコードに書かれてるのは → の具体的な方法。
→ から Ａ や Ｂ を炙り出して推測しないといけないから、だから他人の書いたソースコードって読むのが難しいわけ。
自分で書いたソースコードなら暗黙に Ａ や Ｂ を頭に思い浮かべながらソースコード（→）を読めるけど、
他人のソースコード（→）”だけ”を渡されたら、まず Ａ や Ｂ を → から炙り出して推測するという手間が必要となるわけ。
その手間を軽減するためにコメントがあるわけで、または設計書や仕様書のような、とにかく Ａ や Ｂ を炙り出ししなくても知れる手段が用意されてるのは、有用なことだと思います。
だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。
Ａ と Ｂ を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード（→）の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。
そこのバランスの問題だと思うわ。
Re: (スコア:0)
> Ａ と Ｂ を説明しとくに止めてればそれは有用な情報なのに、気を利かせてソースコード（→）の中身まで過度に説明しだすと、それは逆に身動きしづらくする鎖になるので良くない。
それは書いた奴が無能なだけ
駄目な仕様書の典型じゃん
たまにいるよね、大昔の知識で止まってたり技術者としては並以下なのにソースコードやSQLを中途半端に書いてきて足枷ばかりはめようとするアホ
Re: (スコア:0)
>だけど、 → の中身まで懇々と説明しだすと、それはソースコード読めば良いじゃない。ということになる。
逆に、中身は邪魔です。
仕様が網羅されているかを見るのに、コードに引っ張られて見てしまい、バグが有る時は作成者と同じ穴に嵌りがち。
純粋に「A→B」が「何をしたいのか？」って点で表現されている物の方がずっと良い。
運用や運用支援の立場から (スコア:2)
運用や運用支援をしている立場からの意見ですが。
「本番環境で動かすもの」なら、設計書はほしいです。
トラブルが発生したとき、即時の対応が必要なときに、
すべてのプログラムソースや設定ファイルを追って「問題を関係する箇所」を探している「時間的余裕」はありません。
設計書と事象から「問題に関係する箇所」を推定し、
実行状況や入力データの不健全さを疑い、
必要があれば「コードのバグ」を疑い、その箇所のプログラムソースを確認します。
コードのバグとして扱うのは、一番最後ですが、
設計書がないなら「本番で不具合を起こした」ことから、
「設計ミス」や「現実に則した動作をしないもの(バグを内包)」
として、コードの納入元に即時の調査対応を求めることをエンドユーザーから求められます。
「コードを追う」までは、運用の契約に含まれていないことが多いのです。
運用や運用支援をしている身からすると、大変面倒だし、回復まで時間がかかるので、
「本番環境で動かすもの」なら設計書をつけてほしいです。
Re: (スコア:0)
ドキュメントが作られていても、「何をしたいか（したかったか）」が分からなければ意味は無いですよね。
逆にコメントやソースや自動作成ドキュメントであっても、「何をしたいか（したかったか）」が判るようになっていれば問題無いですよね。
正確には「コメントや自動作成ドキュメントなんてやくに立たない」ではなく
「(ドキュメント作成能力にない人間による)ドキュメントやコメントや自動作成ドキュメントなんてやくに立たない」
ではないでしょうか。自動生成で「何をしたいか（したかったか）」が出力されるよう書かれたソースなら全て解決。
Re: (スコア:0)
「何をしたいか（したかったか）」
これは理論的にコメントや自動作成ドキュメントからは本質的に作成不可能なんですよ。
なぜか。
何かバグがあったとします。
「何をしたいか、したかったか（要求、仕様、設計）」と「何をしているか(ソースコード)」が乖離しているからバグがあるわけです。結局出来上がるものは本来の「何がしたかったか」はわからないのです。
なので、自動作成ドキュメントでできたもの（だけ）なんて、メンテ時には役に立たないんですよ。ほとんどの場合。
Re: (スコア:0)
うんうん。
内容が理解できないと、形式しかケチをつけるところがないよね。
Re: (スコア:0)
レビューで誤字脱字ばかりチェックしている自称有識者思い出した
Re: (スコア:0)
意識高いってやつですか？
Re: (スコア:0)
有識者＝意識が有ります。寝てません。という事なのだろう。
私には意識がありますと自称する存在に意識はあるかというのは難しい問題ですね。
Re: (スコア:0)
元コメの指摘は全うだと思われるが･･･typoとか枝葉松葉は拘るとこじゃないかと。
設計書はそういうのはすげー欲しいですよ。
＃ ソースコメントも、X + Y = B 的なコメントを書く人がなんと多いことか。
＃ 「iに5を足す」が無駄なのは分かっても「listにIDを追加する」が同レベルなことには気づかないんですよねぇ･･･。
Re: (スコア:0)
こういう揚げ足取りで足引っ張るしか能がない人がいなくなれば
仕様書を書く時間が増えて全て解決するんだがなｗ
Re: (スコア:0)
> こういう揚げ足取りで足引っ張るしか能がない人がいなくなれば
> 仕様書を書く時間が増えて全て解決するんだがなｗ
設計書をまともに書く人は、指摘されて修正することに安心を感じるんだけど、
たまに設計書に指摘すると揚げ足取りで足引っ張るとかいう人いるよね？
間違いを指摘するのがめんどくさくなる。
Re: (スコア:0)
> 設計書をまともに書く人は、指摘されて修正することに安心を感じるんだけど、
しかし残念ながらここは投稿内容を修正できないスラドなのであった。
正当な指摘であっても本筋に関係なければ議論の邪魔と斬り捨てられても仕方ないと思う。ここはそういう場だよ。
Re: (スコア:0)
これはTypoの指摘や揚げ足取りじゃないだろ。
たとえばIPｖ4の話をしている時に、アドレスの例として10.72.0.382とか言う奴がいたら、そいつの
技術的見解や仕事の進め方についての発言に何の意味もない事はわかるだろう。
十分に慣れ親しんでている人間なら気持ち悪さに耐えられないはずの事に気が付かないってことだから。
そういう種類の間違いだと思うぞ。
Re: (スコア:0)
> 10.72.0.382
10.72.30.82 のtypoかもしれないし、間違う理由は人それぞれ。
なのにたった一点を見て全体を判断する行為こそが愚かではなかろうか。
実際わたしの周囲にも、英語が苦手で、ディスクトップとかインストロールとか
そういうレベルの単語を連発する人がいるが、その人のプログラムは群を抜いて優秀。
その人のアウトプットのバグ率の低さは半端ない。
でも毎年、新人は馬鹿にすんだな、その人を。すぐに認識を改めるけどさ。
Re:設計書と一言で言っても (スコア:1)
＞でも毎年、新人は馬鹿にすんだな、その人を。すぐに認識を改めるけどさ。
その人のことをもっと知りたいのでもっと紹介いただける部分があったらぜひ書いていただきたいです。
Re: (スコア:0)
それはプログラミング言語ではなくて英語というか外来語の話でしょ。しかも発音の話。まさかその人disktopとかinstrollとか書いたり打ったりするの？
十分に経験のある人であれば、代入先を右に書いたり、1オクテッドが255を越えるアドレスを書いたりなんて事は指が拒否するだろう。いつもやってることなんだからわざとじゃない限りそういう間違え方は出来ない。
野球経験者にバットを握らせたとき、どんなに慌てていてもどっちの手が上になるか間違えるなんて事はあり得ないのと同じ、
Re: (スコア:0)
「綴りが正しいか」も「英語というか外来語の話」の一例に過ぎませんし、間違っててもそれは本質ではない、と思いますよ。
IPアドレスだと無効な入力として「999.999.999.999」と設定するUIもたまに見るし、指が拒否するレベルかなぁ…？
APIの名前の綴りとか、実際に使用する値として不正値入れてたらそりゃダメだけど、
単語自体が可読性以上の意味を持たない部分でのtypoや、例である事が明確な文脈での不正値も本質とは無関係だしどうでもいいでしょう。
ところで私は8ビットの単位をオクテットって覚えてるんですけど、オクテッ「ド」が正しいんですかね？
# あと代入先が右って言語や環境は主流ではないけど普通にありますよ。
# 有名所だとアセンブラのAT&Tシンタックス。代入先などが右に来る。超キモい。
Re: (スコア:0)
ね、気になるでしょう？
octetをどう読んでも「ド」の音は出てきませんからね。
Re:設計書と一言で言っても (スコア:1)
＞もっと上流の業務寄りな文書って必要だと思う。
これだな。
ソース読めば詳細はわかるけど、全体が見えない（見えるまで時間がかかる）
全体像、設計思想、設計の意図、データフロー、業務フロー、入出力設計書、データ定義書ぐらいは必要。
逆に、下流の「プログラム設計書」とか、正直いらんと思う。
#ソースコードとプログラム設計書（ソースコードと1対1に対応）渡されて、引き継ぎ終わり言われてもねぇ・・・
Re: (スコア:0)
DB 設計書って言っても、
Excel の表にフィールド並べて1行コメントしてあるだけってレベルの多いし
そのレベルで問題ないなら SQL にコメント入れとけば十分だって
Re: (スコア:0)
そういうのは普通テーブルデザイナーツール使ってSQLとテーブル仕様書を自動生成するとコメントつきのSQLとExcelと生成してくれるでしょ
Re: (スコア:0)
一番書きたいcreate tableなんて、
管理しているソースではカンマで複数行にしているけど、
丸括弧の中は一行で、マイナスマイナスから始まる行コメント
を書くとエラーなのでは？
どう書けば良いのでしょう？
Re:設計書と一言で言っても (スコア:1)
ソースコードのコメントを抜いて、COMMENT を追加するスクリプト通せばいいだけじゃない？
Re: (スコア:0)
少なくとも PostgreSQL、SQLite3 に関しては
-- は C/C++ で言うところの行末までの1行コメント // なので
のような書き方は出来ますよ。
Re: (スコア:0)
> もっと上流の業務寄りな文書って
マニュアルという形で作ることはありますね。
ユーザーにわかる内容、機能の目的などを記載。
ユーザー目線になると違った操作感を見つけたりするので良い見直し材料になります。
設計書よりは見てもらう可能性が高いような気もする
(ユーザーは基本的にマニュアルなんて見ませんが、ごく稀に見てくれる方もいるのです。)
見直しのレベル感が個人の力量に依ってしまうのが難点ですが。