- 1 名前：デフォルトの名無しさん [03/10/05 23:34]
- おまえら、自分で作ったプログラムについての、わかりやすく的確な
ドキュメントを書ける自信はあるか？
仕事で納品したり、他人に見せるプログラムとして公開するつもりなら、
マニュアルや、仕様書などのドキュメントを書く機会は必ずある。
プログラムとドキュメントはとても関係が深い。ドキュメントが整っていない
プログラムなど、ゴミと同じ。それに、ただ書けばいいって物でもない。
ドキュメントがゴミ程の役にも立たなければ、結局それはゴミなのだ。
だらだらと書いた意味不明な文章を他人に見られるのも恥ずかしいよな？
いわばドキュメントを書く技術はプログラマの必須スキルの１つなのだが、
実際は、下手糞なドキュメントが蔓延っている。(これはGNU製に多い)
読んでも無駄とか、書いても無駄とか思ってる奴、その考えを改めろ。
プログラムに対するドキュメントを、ちゃんとした１作品として、
後世に残せるよう努力すべきだろう。
今一度問う。
おまえら、わかりやすく的確なドキュメントを書ける自信はあるか？
- 2 名前：デフォルトの名無しさん mailto:sage [03/10/05 23:36]
- あります。
■■■■■■■■■■■■■■■■■■■終了■■■■■■■■■■■■■■■■■■■■■
- 3 名前：デフォルトの名無しさん mailto:sage [03/10/05 23:37]
- >(これはGNU製に多い)
これは偏見じゃねーか？（ｗ
まあ否定する要素もないけど。
- 4 名前：デフォルトの名無しさん mailto:sage [03/10/05 23:38]
- ドキュメント化軽視はアンチパターンだな。
プロジェクトの存続にも関わる。
- 5 名前：デフォルトの名無しさん mailto:sage [03/10/05 23:41]
- ソース＝ドキュメント
とか言うやつはアホだな。
- 6 名前：デフォルトの名無しさん [03/10/05 23:44]
- umlじゃだめですか？
- 7 名前：デフォルトの名無しさん mailto:sage [03/10/05 23:45]
- マ板でやってくれ。
- 8 名前：デフォルトの名無しさん [03/10/05 23:47]
- そだね。
そもそも今までム板にドキュメントの書き方系のスレが無いってのがちょっと気になった。
みんな関心が無いのか、それともＤＱＮなドキュメント書いてる奴は自覚が無いのか。
- 9 名前：デフォルトの名無しさん [03/10/05 23:47]
- ソースと双方向でできる奴なら手間もかからずいいかな。
それ以外は最終的にはソース見ろになるから、詳細レベルは不要。
設計時は通じるレベルで記述して、後は仕様書作成ツール様に任せる。
- 10 名前：デフォルトの名無しさん mailto:sage [03/10/05 23:48]
- >>7
こういう話題もマ板なの？
ドキュメントを記述する上での技術的な話題とすれば、
ム板でもいい気がするけど。
- 11 名前：デフォルトの名無しさん mailto:sage [03/10/05 23:51]
- >>8
会社によってフォーマットがあまりにも違うので語りようがなかったりして。
ちなみにうちは検査に出すドキュメントに決められたフォーマットはなし（笑
- 12 名前：デフォルトの名無しさん mailto:sage [03/10/05 23:54]
- 社内的には分からんでもないが、社外的には綺麗なドキュメント残すと次の仕事が
取り辛くなっちゃうから意図的に残さないｗ
- 13 名前：デフォルトの名無しさん mailto:sage [03/10/05 23:54]
- ドキュメント書く上ではまず、ソースとの同期という問題がある。
これはソースとドキュメントが別ファイルなのが問題ではないか？
ということで、doxygenみたいなツールを使うことである程度緩和される。
ただしdoxygenはC++専用。
各言語毎にこういうツールを用意する必要がある。
- 14 名前：デフォルトの名無しさん mailto:sage [03/10/05 23:57]
- >>1
自信ないよ。
四苦八苦しながら書いてる。
それで、教えてくれるの？
- 15 名前：デフォルトの名無しさん [03/10/05 23:58]
- マニュアル対する不満の多くは，「どこに書いてあるかわからない」「書いてあることの意味がわからない」といった，“わかりにくさ”にあります。
マニュアルの「わかりやすさ」とは，①書いてあることの意味がわかる，②どこに書いてあるかわかる，③知りたいことが書いてあるの３点です。
- 16 名前：デフォルトの名無しさん [03/10/05 23:59]
- 関数呼び出しグラフを生成してくれるようなツールってありますか？
graphvizのフォーマットで書き出してくれるだけでもいいんですが。
- 17 名前：デフォルトの名無しさん mailto:sage [03/10/06 00:01]
- >>16
言語・環境を書けよ。
- 18 名前：デフォルトの名無しさん [03/10/06 00:02]
- うっかりしてました。
C++でお願いします。
- 19 名前：デフォルトの名無しさん [03/10/06 00:02]
- 書いてあることの意味が分かる－－伝わりやすい文章
企画段階で想定したマニュアルの利用者（読み手）の知識・技術・能力
のレベルに合わせて，理解しやすく，読みやすい文章を書くようにします。
短い文を心掛ける－－１センテンスは３５～５０文字位が適当
１センテンスが長文だと，意味を読みとり難くなります。１センテンス
３５～５０文字を目安として，１つの文脈を表すようにします。
接続詞の使い方に注意を
「そのうえ」，「さらに」，「しかし」など，接続詞で文章をつなぐと，
めりはりのない文章になりがちです。
読点の使い方
また，主語には原則として読点（，，）をうちます。こうすることに
よって主語と述語の関係が明確となります。これにより読み手の
意味の取り違えや，読み誤りを防ぎます。
「です。ます調」で，使用者（読み手）の共感を得る
「です，ます調」は，読み手が親近感を持つ表現であるところから，
読む気を引き出す，あるいは，“利用者の共感を得る”といった観点
から，マニュアルに適した文体です。
なお，「である調」は，事実を正確，簡潔に表現するのに適した文体
です。
- 20 名前：デフォルトの名無しさん [03/10/06 00:04]
- 以上はここからのコピペ
ttp://www2s.biglobe.ne.jp/~kobayasi/manual/manual06.htm
よくまとまってるので、指標にはなるんじゃないかな
- 21 名前：デフォルトの名無しさん mailto:sage [03/10/06 00:12]
- >>16
そういうのDOS時代にはあったな。
関数の呼び出し関係を木構造で出力するやつ。
graphvizみたいなグラフじゃないけど。
doxygenじゃ手動でも書けないんだっけ？
- 22 名前：14 mailto:sage [03/10/06 00:19]
- >>20
おお、ありがとん。
文章に関しては参考にしてみる。
- 23 名前：デフォルトの名無しさん [03/10/06 17:09]
- 外国にはマニュアルライターって職業があるの
- 24 名前：デフォルトの名無しさん mailto:sage [03/10/06 17:14]
- 日本でもいますが。
- 25 名前：デフォルトの名無しさん mailto:sage [03/10/06 18:38]
- 下手なマニュアル仕様書よりも、Ｃ＃、ＶＢ．ＮＥＴ、Ｊ＃、
Ｊａｖａ等のＳｔｒｉｃｔな言語でほぼ実際の動きをエミュ
レートするソースがあれば、当面はそれ
に勝るマニュアルや仕様書はないんじゃないのか？
１０年位して、バージョンアップが殆ど無くなった段階で
初めて詳細な仕様書やマニュアルを日常語に近い言葉で
書けばＯＫじゃないの？
- 26 名前：デフォルトの名無しさん mailto:sage [03/10/06 21:06]
- いいえ、仕様書は必要です。
- 27 名前：デフォルトの名無しさん mailto:sage [03/10/06 21:40]
- だからソースも仕様書の一部だと思えば良いってこと。（そのソースで生成
されたコードは売り物にならないと思うべきだが）
というか、大抵の場合、日常語で書かれた仕様書というのは、多かれ少なかれ
顧客の業務の重要な情報を含むことが多いわけで、書かれたものは基本的に
顧客に返却して管理させるべきもので、それをどこの馬の骨ともわからない
人間に見せてダイレクトにコード化させることが犯罪的なんだよ。
まだ良心的な会社は、それじゃまずいから、意図的にコーディング上重要な
情報を小出しにし過ぎる。実装不能な仕様を渡されてそれをコード屋のせいに
する。丁度中間のバッファが必要なわけだ。少なくとも実動作する程度のもの
を作って、その中で守秘義務上、伏せておきたい情報を隠蔽すればいいわけだ。
論理的に数分割して時間差をつけて別会社に発注するだけで情報漏洩はかなり
防げる。
- 28 名前：デフォルトの名無しさん mailto:sage [03/10/06 21:45]
- 25==27?
論理設計書、物理設計書
外部設計書、内部設計書
基本設計書、詳細設計書
システム設計書、プログラム設計書
呼び方はいろいろだが、いったいどのレベルの設計書の話をしてるんだ？
- 29 名前：デフォルトの名無しさん mailto:sage [03/10/07 05:47]
- 構想書・提案書・稟議書：漠然としたアイデア。Power-PointやFlash-Animation
とかを使ってイメージを表現すればよい。
計画書：アイデアを前向きに検討する時に作成される。論理的に矛盾が無いか
算術的に不可能ではないか、統計的パラメータの準備は十分か、検証される。
体系的でなく、断片的なものの集積。
Word（論理的妥当性）/Excel（算術的妥当性）/Access（統計的妥当性を使
って書かれる。決してこの段階では仕様書とは呼ばない筈であるが、何故か
この国では仕様書と呼ばれる。
設計書：基本計画がまとまった後、上記計画書群をもとにそれらをつなぎあわせて
一枚の設計書にする。この際に厳格なライブラリを持った言語が好ましいことは
言うまでも無い。.NETやJava等が適している。仮想マシン上で正常動作すること
が大前提。しかし、設計書が完成してもまだ実装段階ではない。
＋αが重要。
＋αとは、プログラムに含まれているパラメータに調整要素をつけること。その
調整要素に優先順位を指定すること。これを行う為には熟練が必要。
この調整パラメータを含んだ設計書が規格書。
実際のコーディングは規格書に基づいて行われるべきである。しかし実装段階
では、調整パラメータを利用した修正が不可避的に必要。（ロジックやアルゴリ
ズムの修正は余りない。環境固有の要素やハードウェアの物理的側面から多少の
変更はあるが、パラメータ修正に較べれば小さい）パラメータ変更は上流に
フィードバックされ、規格書の変更を余儀なくさせる。
これを繰り返して、規格書が仕様書に近付いていく。
結論：
仕様書が出来る前に必ずブツが出来る。
いきなり仕様書を書ける奴は神。
- 30 名前：デフォルトの名無しさん mailto:sage [03/10/07 10:16]
- >>29
「規格書」とはなんしょうか？その説明が無いので、あなたのいう「仕様書」がなんなのか
よくわかりません。
それから普通は「構想書・提案書・稟議書」と「計画書」の間になにかあると思います。
日本語では『要求仕様書』、アメリカでもrequirement specificationと言うと思います。
- 31 名前：デフォルトの名無しさん mailto:sage [03/10/07 10:18]
- >>30
あ、すみません。規格書の説明はありましたね。第一パラグラフは取り消します。
- 32 名前：デフォルトの名無しさん mailto:sage [03/10/07 10:22]
- ところで、ワインバーグも『要求仕様の探求学』という書籍を出しているのをみると
わかるとおもいますが、システムを作る入り口となるものは「要求仕様」であり、
それを書類にしたものが要求仕様書で、この位置づけの仕様書が無いとシステムが
作れないと思います。
- 33 名前：デフォルトの名無しさん mailto:sage [03/10/07 10:45]
- >>29
どの分野の人？
パッケージ？ゲーム？情シスの人？
- 34 名前：デフォルトの名無しさん mailto:sage [03/10/08 20:54]
- 総合計画書を作るまでは、期待と夢が膨らんでいく段階。この段階は要求定義書
とは言わず、計画書群の一部だろな。
ただ総合計画書を作る段階でどんどん要求が絞り込まれていく。
これは予算とか工期などの生臭い要求も関係してくるというか、殆どの場合
がそれ。この過程でそれまでの前向きな基調だった計画書群とは異なって
やや後ろ向きな要求定義書と呼ばれるバージョンが出てくる。総合計画書
を作る段階では意外に高い影響力を持つ。だから計画書を書かされた人間は
要求定義書を書いた奴を内心憎んだりする。
なお、総合計画書を書く段階で、実装には無関係という前提のもとで、
一応完結的なアプリケーションの形にしても良い。（勿論ソースも残す）
かなり細かい部分まで記述可能な例えばDelphi等を使うと良い。Delphiは
総合計画書を書く段階で最も活躍する言語かも知れない。（但し長期的に
使うのには色々と問題があるので、継続的に使用してはならないと思うべ
きだが）これは企画書を書く段階の助けになるからである。
- 35 名前：デフォルトの名無しさん mailto:sage [03/10/08 23:01]
- なんかこの長文書いてる人、違う世界の人みたい。
- 36 名前：デフォルトの名無しさん mailto:sage [03/10/08 23:48]
- 読みにくいなぁ。才能無さげ。
- 37 名前：デフォルトの名無しさん [03/10/09 06:13]
- 漢字が多い文章も考えものだと34を見てｵﾓ-ﾀ
- 38 名前：デフォルトの名無しさん mailto:sage [03/10/09 07:29]
- GUIなんかは、直感でわかるだろ。
D'ont think feel!
- 39 名前：デフォルトの名無しさん [03/10/09 07:53]
- 誰か34を読める文章に書き換えれ
- 40 名前：デフォルトの名無しさん mailto:sage [03/10/09 08:00]
- > D'ont think feel!
何語ですか？
- 41 名前：デフォルトの名無しさん [03/10/09 08:08]
- >>39 書き換えてみますた。
総合計画書を作るまでは夢。要求定義書はなんつうかもう空絵事。
総合計画書を作る段階でどんどん退化。
生臭い要求も関係してくる。この過程で夢は消える。
要求定義書は、総合計画書を作るときやけに高い影響力を持つ。
だから計画書を書かされた人間は
要求定義書を書いた奴を脳内でぶちのめす。(-_-#)< FackYou!
総合計画書を書くときDelphiでプロトタイプ作っても良さげ。
(ただしそのまま開発にDelphi使うと問題が多発するという諸刃の剣)
まあ、企画書を書く段階の助けにはなるだろうってこった。
- 42 名前：デフォルトの名無しさん mailto:sage [03/10/09 12:09]
- Delpiでは持続的開発は難しいだろな。
瞬間的に巨大なものを作るのは得意かも知れないが。
- 43 名前：デフォルトの名無しさん mailto:sage [03/10/09 20:02]
- a
- 44 名前：デフォルトの名無しさん mailto:sage [03/10/10 06:52]
- そんな、持続的に長期手直しがあるのが判ってるなら
スクリプトを導入すればいいのに。
ちょっと直す都度コンパイラのコードに手を入れるなんて・・・まるでCOBOLだ。
- 45 名前：デフォルトの名無しさん mailto:sage [03/10/10 16:37]
- Script言語のような「軽い」言語を動かせる環境は、UnixのShellとか
Web-browserだとか非常に永続性の高い重く巨大で安定した土台がある
からこそ動くわけ。
この土台を構築するのには膨大な金がかかっている。（見た目そっくりなものは
簡単に作れるが）
Script言語を動かしても壊れない土台は実はそう短い時間じゃ作れない。
あと、こういった安定土台＋Script＝理想と考えるのは間違い。
重く巨大な土台が影響して、実は本当に大きな環境激変に耐えられなかったり
する。（ちょっとした変化なら、他よりも非常に巧く対応するが）
- 46 名前：デフォルトの名無しさん mailto:sage [03/10/10 18:36]
- >>44
いやスクリプトといっても有名所の肥大化したものじゃなくて
せいぜい5千行くらいで書けるような小さなものでも結構役立つよ。
自分は色々作ってやってる。テキストをそのまま実行するものと
もう少し速度が必要な用に中間言語型の２つね。
さっきも仕様変更のメール来たけど、スクリプトの部分だけ変更してメールで送った所だ。
Delphiはバリアント型があるのと、実行時型情報のおかげでスクリプトが簡単に作れて組み込めるのがありがたい。
- 47 名前：デフォルトの名無しさん mailto:sage [03/10/11 15:41]
- Web-browserっていわいるIEなどの、ブラウザのことですか？
- 48 名前：デフォルトの名無しさん mailto:sage [03/10/14 07:54]
- ハードウェアがあって、CPUを組み合わせてシステムを作る。
ＯＳが必要になり、ＯＳ固有のライブラリでアプリを作る。
優秀なアプリの上にスクリプト言語やマクロ言語が発生し
やがてそのアプリはＯＳのサブ環境に近づいていく。
スクリプト言語もやがてライブラリが整理され、文法も
補われて単なる言語になる。その言語で書かれたアプリが
再び環境となって....
こうして、ＯＳの上にＯＳが出来てさらにその上にＯＳが
出来るという無限連鎖が発生するように見える。ＣＰＵの
スピードアップはそれを普通に可能にする。
ただこういうのを砂上の楼閣というんだろうね。最終的に
使うのは人だから、上が崩れると下まで巻き込んで、すべて
崩れてしまう。その危険性を日頃から意識しているかいないかで
長期的にみてぜんぜん違ってくる。
- 49 名前：デフォルトの名無しさん mailto:sage [03/10/14 09:52]
- 発生しないよ。
- 50 名前：デフォルトの名無しさん [03/10/14 23:34]
- 要するにそのうちJavaと.NET両方で動く言語ができるってことでつか？
- 51 名前：デフォルトの名無しさん mailto:sage [03/10/14 23:37]
- J#とJavaでJavaはすでに両方で動いてますね。
- 52 名前：デフォルトの名無しさん [03/10/15 01:12]
- C#もJVMで動くのかな？
- 53 名前：デフォルトの名無しさん mailto:sage [03/10/15 01:21]
- >>51
ライブラリが違いすぎ。
言語仕様なんてライブラリに比べたら問題にならないでしょ。
- 54 名前：デフォルトの名無しさん [03/10/15 01:22]
- どうせクラス仕様書なんか作っても、素人の客は理解なんかできないだろ。
適当でいいんだよ。
- 55 名前：デフォルトの名無しさん mailto:sage [03/10/16 03:25]
- 少なくともJavaで書かれたソースコードは、これは「ソフトウェア」じゃ
ない。「ダイアモンドウェア」であってハードウェアよりもず～っと硬い。
これを現実のハードに適用するとどういう結果を招くか。つまりJavaで
書かれたソースはあくまでも実装準備段階で、別にもう一度ソース最初から
書き直さなければならないってことね。真に良いソフトウェアを書く為には
ダイアモンドのように硬いソースが必要だったりすることもあるから
Javaの存在価値はMSが言うほど小さいものではなかったりする。
ただしそれは十分に柔らく書き直してから使うべきだろうけどね。
- 56 名前：デフォルトの名無しさん mailto:sage [03/10/16 03:32]
- 誰か>>55を日本語に直してくれ。
- 57 名前：デフォルトの名無しさん mailto:sage [03/10/16 11:54]
- >>56
>>55をexcite翻訳を使って英訳、
できなかった部分は原文を意味が変わらない程度にいじって再び英訳、
そしてそれを邦訳。結果はこれ。
Javaによって少なくとも書かれたソース・コードについては、
これが「ソフトウェア」にあります。何もありません。
それは「ダイヤモンドの着用」で、ハードウェアよりはるかに困難です。
これが応用の困難な[現実]である場合、
どんな結果が引き起こされるでしょうか。
で、すなわち、書かれたソースがそうであるJava、
最後への増大する準備段階でもう一度独立して始まるソースから。
書き直しに対して持っています。
ハードソースがダイヤモンドのように時々要求されるので、
非常によいソフトウェアを書くために、
Javaの存在価値はMSが言うほど小さくありません。
しかしながら、それは十分に柔らかに書き直した後に使用されるべきですか。
- 58 名前：デフォルトの名無しさん [03/10/16 14:41]
- ようするに、スクリプトを作って、スクリプトの解説を書いておけば
あとはスクリプトが仕様書って事かい？
- 59 名前：デフォルトの名無しさん [03/10/16 17:27]
- 仕様書は書いたって誰も読まないから、嘘が書いてなければいい。
保守するときだって仕様書なんか信用しない。
「地図と土地が一致していなければ必ず土地の方を信用しろ」の格言のとおり、
「ソースと仕様書一致していなければ必ずソースの方を信用しろ」なんだ。
仕様書がいくら立派でも、保守不能な（保守が現実的でない）ソースは
保守不能なんだ。
- 60 名前：デフォルトの名無しさん mailto:age [03/10/16 17:37]
- 人権尊重の個人主義社会（都会的自由人） ⇔ Ａ型中心の集団主義的村社会（封建的田舎人）
相容れない？
集団主義社会＝北朝鮮、戦前の日本。
www.pref.aichi.jp/jinken/century01.html
「人権の世紀」という言葉を聞いたことがありますか？
労働相談・ご意見
www.jtuc-rengo.or.jp/new/sodan/mail/rodo_sodan.html
- 61 名前：デフォルトの名無しさん mailto:age [03/10/16 17:37]
- ＜血液型Ａ型の一般的な特徴（改訂版）＞（「自分だけいい子」は直そう！）
●とにかく臆病・神経質で気が小さいだけ（真に他人を思いやる気持ちには欠けている、二言目には「世間」(「世間」と言っても、一部のＡ型を中心とした一部の人間の動向に過ぎない））。
●異常に他人に干渉して自分たちの古いシキタリを押し付け、そこから少しでも外れる奴に対しては好戦的でファイト満々な態度をとり、かなりキモイ（偏狭、自己中心、硬直的でデリカシーがない）。
●妙に気位が高く、自分が馬鹿にされるとカッと怒るくせに平気で他人を馬鹿にしようとする（ただし、相手を表面的・形式的にしか判断できず(早合点・誤解の名人)、内面的・実質的には負けていることが多い）。
●基本的に悲観主義でマイナス思考なため性格が鬱陶しい（根暗・陰気)。
●とにかく否定的でうざく、粗探しだけは名人級（例え10の長所があっても褒めることをせず、たった１つの欠点を見つけては貶す）。
●社会的強者には平身低頭だが、社会的弱者に対しては八つ当たり等していじめる（強い者にはへつらい、弱い者に対してはいじめる(人が見ていないときは、より一層））。
●少数派の異質・異文化を理解しようとせず、あるいは理解を示さず、排斥する(多数派＝正しい と信じて疑わない、了見が狭い差別主義者）。
●何でも「右へ習え」で、単独では何もできない（群れでしか行動できないヘタレ）。そのくせ、集団によるいじめのリーダーとなり皆を先導する（陰湿かつ陰険で狡猾）。
●他人の悪口・陰口を非常に好むと同時に、自分は他人からどう見られているか、人の目を異常に気にする（自分がウソツキだから他人のことも容易に信用できない、ポーズだけで中身を伴っていない）。
●友人関係は、表面的な浅い付き合いでしかなく、心の友はおらず孤独（他人の痛みがわからず、包容力がなく、冷酷だから）。
●頭が硬く融通が利かないため、すぐにストレスを溜め、また短気で、すぐに爆発させる（不合理な馬鹿）。
●後で自分の誤りに気づいた場合でも、素直に謝れず強引に筋を通そうとし、こじつけの言い訳ばかりする（社会悪の根源、もう腹を切るしかないだろう！)。
●男は、女々しいあるいは女の腐ったみたいな考え(例：「あいつより俺のほうが男前やのに、なんでやねん！（あいつの足を引っ張ってやる！！）」）。
- 62 名前：デフォルトの名無しさん mailto:sage [03/10/16 17:51]
- 仕様書候補と実装ソースは互いに尊重しあって、相互にそれを修正し
ていって成長するもの。仕様書候補を書こうというものは実装ソース
を書く人のニーズを真に理解していなければならないし、実装者も
仕様書候補の行間を読んで真に必要とされているものを生かしていか
なければならない。
最初に完成された仕様書があって環境毎に異なるバリエーションを持
ちえるプログラムコードはそれに従属し翻訳されたものであるという
考え方は最終的な結果論であり理想論。
というか、その状態になって初めて「仮想原本」たる仕様書と呼べる
水準のものになる。この仕様書の価値こそが極めて高いわけで、これ
が生まれることをほのかに期待するからこそ人はプログラムという邪
道に敢えて入り込むわけ。
ダイヤモンドを散りばめた服が、決して服の究極の代表的な姿にはな
りえないのと同じように、ソフトウェアも硬く鋭く光る部品で構成
されているものが終局的な姿だというわけでもないだろうね。
ま、一度その方向に極端化してみる（洗練と人は言う）というのはそ
れはそれでいて得られるものは大きく貴重なものも多いのだろうが。
- 63 名前：デフォルトの名無しさん mailto:sage [03/10/16 18:26]
- ↑文章が下手糞では説得力も糞もない
- 64 名前：デフォルトの名無しさん mailto:sage [03/10/16 23:03]
- >>62
ちゅーか、ながい。
沢村の友達なんだ炉。
- 65 名前：デフォルトの名無しさん [03/10/16 23:18]
- >>62は>>55だろ
- 66 名前：デフォルトの名無しさん mailto:sage [03/10/16 23:26]
- ダイヤモンド大好きっ子ですね
- 67 名前：(゜Jし゜） mailto:sage [03/10/16 23:27]
- ソースとドキュメントの一致と言う意味では、詳細設計レベルでは
JavaDocみたいなのを使うのが一番だよね。
概要設計レベルならUMLになるのかな？
でも、どっちも理解してくれないウチのPM…
まぁ何を書いても突っ返される訳だが（工数稼ぎのため？）
- 68 名前：デフォルトの名無しさん [03/10/17 02:15]
- doxygen とかで（規約かなんかで）全ての関数インターフェースに
コメントをつけるとしたとき、仮引数名がその意味を完全に表していたときは
１．書かない
→UNDOCUMENTEDの警告がいつも出てしまってほかの警告が霞んでしまう
２．繰り返す：@param instance インスタンス
→かっこわるい
３．空にする：@param instance
→まちがってる気がする
どれがいいんでしょうか？
- 69 名前：デフォルトの名無しさん mailto:sage [03/10/17 06:49]
- 「XXXのインスタンス」とか書くのはだめなの？
- 70 名前：デフォルトの名無しさん mailto:sage [03/10/17 10:40]
- >>68
2
- 71 名前：デフォルトの名無しさん mailto:sage [03/10/17 10:58]
- >>68
４．決めうち：@param instance ソース嫁
- 72 名前：デフォルトの名無しさん mailto:sage [03/10/17 20:37]
- ドキュメント：
自分たちが書くべき言語で書かれた文書のこと。
それを読んで次の工程の人がその人たちが書くべき言語でコードを書く。
C言語で書かれたドキュメントをコンパイラに渡してそれを参考に
アセンブリコード或いは機械語コードに変換する作業をコンパイルと呼び
その作業をする人或いはソフトウェアをコンパイラと呼ぶ。
ソース：自分たちよりも前の工程の人が書いたドキュメント群のことを区別
する為にソースと呼ぶことが多い。
Javaでドキュメントを書いている人たちも、日本語のソースや英語のソース
を読んで書いている場合が多い。多くの場合、それは既にオンライン化され
ている場合が多く、Word・Excel等の上で読めるものであったりすることが多
い。
コード：自分たちの次以降の工程の人が書く文書はコードと呼ぶ。
- 73 名前：デフォルトの名無しさん [03/10/18 23:25]
- 良いドキュメント・マニュアル・仕様書は、
良い会社・環境・人間関係という土台があってこそ
（続きどうぞ
- 74 名前：デフォルトの名無しさん [03/10/19 05:22]
- ●●●マスコミの 「盗聴／盗撮」 は許されるの？その５●●● natto.2ch.net/mass/kako/998/998142751.html
724 名前： 文責：名無しさん 投稿日： 01/09/09 17:52 ID:Na9tEsUs
>>722
＞早朝番組の「占いコーナー」なんて、個人向けメッセージの宝庫かもしれないですね。
雑誌の占い欄もそうですね、以前も書いたけど。
「あなたの成果を横取りする人がでてくるかもしれません。その人の要領の良さに嫉妬しないで」
というアドバイスをある占いから頂きました。でも残念ながら，盗聴の要領の良さは嫉妬の対象になりません。
それに、成果を横取りするよりも、私にとっては、私生活の侵害のほうが遥かに腹立たしいです。
> 口では「マスコミの盗聴」に反対しながら、本音の部分では喜んでるんだろ、と思っている。
だから、盗聴に対する罪悪感がないのだ。その根底にあるのは、
女子アナ・芸能人というものに特別の価値があるという自惚れだ。
あはは、なるほど。そう言えば、盗聴やストーキング行為は、
かっこいい人にならされてもいいと言った、某マスコミ関係者がいたらしい。
された事ないから、わからないんだよね。それを聞いた人が
「なんだ、盗聴されても悪い気はしないんだ」と思い、罪悪感無く盗聴を続ける事になる。
いくら尊敬している人でも、かっこよくても（笑 盗聴がわかった時点で、信用は無くなります。
- 75 名前：デフォルトの名無しさん mailto:sage [03/10/19 06:21]
- ♥
- 76 名前：デフォルトの名無しさん [03/10/21 01:17]
- えーと、仕様書ってのは客に見せるもんなのか
客が読んで役に立つのは要求仕様と運用マニュアルでは･･･
つーか、運用マニュアルって作んないのか･･･
- 77 名前：デフォルトの名無しさん mailto:sage [03/10/21 07:57]
- 俺もそう思う、実際見てくれたことないし。
仕様書ってのは何年後かに変更が発生した場合
自分たち（もしくはその修正を行う別会社）がどういう仕様か
確認するものだとおもてるよ
- 78 名前：デフォルトの名無しさん mailto:sage [03/10/21 17:33]
- 何年後っておまえ・・
- 79 名前：デフォルトの名無しさん mailto:sage [03/10/21 22:25]
-
このスレの文章読みづらいにだけど。
- 80 名前：デフォルトの名無しさん mailto:sage [03/10/21 22:51]
- その「読みズラい」って意見は、79の主観かもしれないよな
ハゲ！
- 81 名前：デフォルトの名無しさん [03/10/25 00:03]
- 『実践！システムドキュメント徹底活用』かってきたよage
- 82 名前：デフォルトの名無しさん [03/10/25 02:04]
- 設計者としてのドキュメント作成技法について書かれた本で
お勧めはありますか？
- 83 名前：デフォルトの名無しさん [03/10/25 02:14]
- つーか、ドキュメントは二の次だ、うごくもんつくれよ。
- 84 名前：デフォルトの名無しさん [03/10/25 02:28]
- >> ソース＝ドキュメント
>> とか言うやつはアホだな。
・・と俺もかつては思っていた、が、ソースコードこそ唯一信頼ができる詳細設計書仕様書だと思うのだ
ＰＧはそれを理解して、可視性の高いソースコードをかかなければならない。
ここでも言われているが、関数仕様書等はdoxygen等でソースから自動抽出が最も実装との差異発生率が少なくて良い
フレームワークや外部仕様リンクの仕様もできればソースに組み込めればベストだと思うが
そのようなツールは現在この世にはない。
従って、クラス図とユースケース程度のものは、自前でドキュメントを残すべきだろう
ドキュメントを大げさにするのはコストの無駄である
ドキュメント作成にコストをかけた分だけ、また、メンテナンス時のコストが発生する。
また、次第に実装との差異が増加する率が高まるだけだ。
- 85 名前：デフォルトの名無しさん mailto:sage [03/10/25 09:35]
- ソースコードをハイパーテキスト化しよう。
- 86 名前：(゜Jし゜） mailto:sage [03/10/25 10:36]
- で、ドキュメント作成する時間を取れなかったので、
コメントに詳細仕様を記述しておいたので、後で暇人を
使ってコメントから仕様書を起草しましょう、と言ったところ、
「結局、ソースを読め！かよ。これだからPGは自分勝手な…」
「ドキュメントきちんと作って…困るんだよねぇ…云々｣
PMさん…コメントと自動生成のリファレンスだけでいいんです…。
ほんとに仕様書書く時間無いんですよ、助けてください。
- 87 名前：デフォルトの名無しさん mailto:sage [03/10/25 12:19]
- そのＰＭにケント・ベックの本でもプレゼントして差し上げましょう。
「今時不勉強なＰＭは生き残れませんよ」って。
- 88 名前：デフォルトの名無しさん mailto:sage [03/10/25 13:07]
- ケント・ベックは、要求されるなら仕様書書けっていってるぞ。
- 89 名前：デフォルトの名無しさん mailto:sage [03/10/25 13:08]
- doxygenで任意の単語にリンク張りたいんだけど、
\anchorや\refいっこいっこ付ける方法しかないですか？
- 90 名前：デフォルトの名無しさん mailto:sage [03/10/25 16:14]
- 設計書と一言で言っても分野や会社によってルールも書き方もまちまちとは思う。書く場合も書かない場合もあるだろう。
本質的には「どんな書類」が「いつ・どの期間」「誰に対して」必要なのかを明確にしておく必要があると思うのだ。
・外部仕様書
大抵の職業PG,SEはある程度規模が大きいソフトウェアを作るだろうから，少なくともマニュアルに近いもの，
一般的にはもっと詳細なものを最初に作るはずだと思う。
更に言えば，殆どの奴らは既存システムの改善（保守）をやっているので，既存の操作の変更があれば，最初に
どことどこを変更って決めたものを書いておかないとユーザ（またはマニュアル部隊）が困るはず。
ユーザに渡す前なら作った後でも良いし，正直最後に微修正が入ることもあるとは思う。
昔ユーザに「ソース読めば？」って言ったプログラマが居たが喧嘩になったよ。もうアホかと…
・詳細設計書
将来の誰かに対して残しておくってこともあるだろうけど，どこをどう直したかを書類としてのこしておかないと
ビルダー（パッケージング）する奴が困ると思うぞ。ちゃんとしたSEなら，どこを直したのか把握して全体の
調整もするはずだ。馬鹿SEも多いが，そういう書類を作って公開しておけば隣近所の奴が何やっているのかも
分かるしね。ソースから読めって奴もいるだろうけど，STABLE な状態ばっかりで開発できる羨ましい環境で
生活してんだなと思うぞ。
んじゃ。
- 91 名前：デフォルトの名無しさん mailto:sage [03/10/25 16:59]
- >>90
すんごいローカル定義だこと。
- 92 名前：(゜Jし゜） mailto:sage [03/10/26 11:50]
- ちなみにそのプロジェクト、外部仕様書は件の暇人を使って
書かせていたのでユーザには迷惑は掛かりませんでしたが…。
そしてそのPMは寄寓にもジャスト35歳だったりして。
結局、自分で書きましたよ、ええ。
後でメンテする人が困るし。
- 93 名前：デフォルトの名無しさん mailto:sage [03/10/26 12:20]
- >>92
きみが書いた仕様書は、誰も解読できないと思うけどね・・・
- 94 名前：(゜Jし゜） mailto:sage [03/10/26 23:59]
- >>93
痛いところを突きますね。
確かに自分の書いた仕様書は自分用のメモみたいな程度のもんでした。
でもまぁ無いよりはましかな、とか思ったもので…。
まーその辺の現実に目を背けたくてこんなスレにいるわけですが。
- 95 名前：デフォルトの名無しさん [03/10/27 13:04]
- 自分はＳＥではなくプログラマーなのですが
プログラマーとしてドキュメントはどんなものを書いていますか？
ウチは外注のソフトハウスで
ＰＭ・ＳＥは元請け会社がやっています。
元請け会社が作った、基本仕様書（仕様書とは名ばかりで、機能が羅列して書いてあるだけ）
を元にプログラムを書くのが
我々の仕事なのですが、
元請け会社に提出用のドキュメントや、
社内の人間に、自分が休んだり辞めたりした後に
他の人でも対応して貰えるように残しておくドキュメントとして
どんなものを作って（書いて）いますか。
ちなみに、今、私は一太郎でドキュメントをシコタマ書いていますが
ドキュメントを書く便利なツールやソフトって無いですか？
- 96 名前：デフォルトの名無しさん mailto:sage [03/10/27 13:18]
- DBから吸い出せば一発で分かるテーブルレイアウト図なんかいりません。
ER図(これもツールで吸いだせるケース多し)と、DFDだけは残してください。
全文検索に引っかかりにくく死蔵になりやすいOffice文書も正直ｲﾔです。
- 97 名前：95 [03/10/27 13:21]
- ちなみにウチの会社
ドキュメントの作成が、みんなマチマチで
ロクなドキュメントを残さないので、
「作った本人しかわかりません、触れません」状態になっており
休みの日にドラブルが起きると
家や携帯に電話が入る。
おちおち、休んでもいられない
杜撰な会社です
- 98 名前：デフォルトの名無しさん mailto:sage [03/10/28 03:47]
- そういや、いくらがんばってドキュメント書いても、誰も読まずに聞いてくる。
- 99 名前：デフォルトの名無しさん mailto:sage [03/10/28 09:49]
- >>98
それはロクなドキュメントじゃないから。
- 100 名前：デフォルトの名無しさん mailto:sage [03/10/28 09:51]
- >>96
テーブルレイアウト図（って何だ？）を見たいと思った人間が、いちいちDBから吸いださずに
すむという理由で、テーブルレイアウト図（って何だ？）は存在しておいたほうがよい。
|
 |
