良いドキュメント・マニュアル・仕様書を書くスレ

1 ：デフォルトの名無しさん：03/10/05 23:34

おまえら、自分で作ったプログラムについての、わかりやすく的確な
ドキュメントを書ける自信はあるか？
仕事で納品したり、他人に見せるプログラムとして公開するつもりなら、
マニュアルや、仕様書などのドキュメントを書く機会は必ずある。

プログラムとドキュメントはとても関係が深い。ドキュメントが整っていない
プログラムなど、ゴミと同じ。それに、ただ書けばいいって物でもない。
ドキュメントがゴミ程の役にも立たなければ、結局それはゴミなのだ。
だらだらと書いた意味不明な文章を他人に見られるのも恥ずかしいよな？

いわばドキュメントを書く技術はプログラマの必須スキルの１つなのだが、
実際は、下手糞なドキュメントが蔓延っている。(これはGNU製に多い)
読んでも無駄とか、書いても無駄とか思ってる奴、その考えを改めろ。
プログラムに対するドキュメントを、ちゃんとした１作品として、
後世に残せるよう努力すべきだろう。

今一度問う。
おまえら、わかりやすく的確なドキュメントを書ける自信はあるか？

2 ：デフォルトの名無しさん：03/10/05 23:36

あります。

■■■■■■■■■■■■■■■■■■■終了■■■■■■■■■■■■■■■■■■■■■

3 ：デフォルトの名無しさん：03/10/05 23:37

>(これはGNU製に多い)
これは偏見じゃねーか？（ｗ
まあ否定する要素もないけど。

4 ：デフォルトの名無しさん：03/10/05 23:38

ドキュメント化軽視はアンチパターンだな。
プロジェクトの存続にも関わる。

5 ：デフォルトの名無しさん：03/10/05 23:41

ソース＝ドキュメント
とか言うやつはアホだな。

6 ：デフォルトの名無しさん：03/10/05 23:44

umlじゃだめですか？

7 ：デフォルトの名無しさん：03/10/05 23:45

マ板でやってくれ。

8 ：デフォルトの名無しさん：03/10/05 23:47

そだね。
そもそも今までム板にドキュメントの書き方系のスレが無いってのがちょっと気になった。
みんな関心が無いのか、それともＤＱＮなドキュメント書いてる奴は自覚が無いのか。

9 ：デフォルトの名無しさん：03/10/05 23:47

ソースと双方向でできる奴なら手間もかからずいいかな。
それ以外は最終的にはソース見ろになるから、詳細レベルは不要。
設計時は通じるレベルで記述して、後は仕様書作成ツール様に任せる。

10 ：デフォルトの名無しさん：03/10/05 23:48

>>7
こういう話題もマ板なの？
ドキュメントを記述する上での技術的な話題とすれば、
ム板でもいい気がするけど。

11 ：デフォルトの名無しさん：03/10/05 23:51

>>8
会社によってフォーマットがあまりにも違うので語りようがなかったりして。
ちなみにうちは検査に出すドキュメントに決められたフォーマットはなし（笑

12 ：デフォルトの名無しさん：03/10/05 23:54

社内的には分からんでもないが、社外的には綺麗なドキュメント残すと次の仕事が
取り辛くなっちゃうから意図的に残さないｗ

13 ：デフォルトの名無しさん：03/10/05 23:54

ドキュメント書く上ではまず、ソースとの同期という問題がある。
これはソースとドキュメントが別ファイルなのが問題ではないか？
ということで、doxygenみたいなツールを使うことである程度緩和される。
ただしdoxygenはC++専用。
各言語毎にこういうツールを用意する必要がある。

14 ：デフォルトの名無しさん：03/10/05 23:57

>>1
自信ないよ。
四苦八苦しながら書いてる。
それで、教えてくれるの？

15 ：デフォルトの名無しさん：03/10/05 23:58

マニュアル対する不満の多くは，「どこに書いてあるかわからない」「書いてあることの意味がわからない」といった，“わかりにくさ”にあります。
　マニュアルの「わかりやすさ」とは，①書いてあることの意味がわかる，②どこに書いてあるかわかる，③知りたいことが書いてあるの３点です。

16 ：デフォルトの名無しさん：03/10/05 23:59

関数呼び出しグラフを生成してくれるようなツールってありますか？

graphvizのフォーマットで書き出してくれるだけでもいいんですが。

17 ：デフォルトの名無しさん：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 ：デフォルトの名無しさん：03/10/06 00:12

>>16
そういうのDOS時代にはあったな。
関数の呼び出し関係を木構造で出力するやつ。
graphvizみたいなグラフじゃないけど。
doxygenじゃ手動でも書けないんだっけ？

22 ：14：03/10/06 00:19

>>20
おお、ありがとん。
文章に関しては参考にしてみる。

23 ：デフォルトの名無しさん：03/10/06 17:09

外国にはマニュアルライターって職業があるの

24 ：デフォルトの名無しさん：03/10/06 17:14

日本でもいますが。

25 ：デフォルトの名無しさん：03/10/06 18:38

下手なマニュアル仕様書よりも、Ｃ＃、ＶＢ．ＮＥＴ、Ｊ＃、
Ｊａｖａ等のＳｔｒｉｃｔな言語でほぼ実際の動きをエミュ
レートするソースがあれば、当面はそれ
に勝るマニュアルや仕様書はないんじゃないのか？
１０年位して、バージョンアップが殆ど無くなった段階で
初めて詳細な仕様書やマニュアルを日常語に近い言葉で
書けばＯＫじゃないの？

26 ：デフォルトの名無しさん：03/10/06 21:06

いいえ、仕様書は必要です。

27 ：デフォルトの名無しさん：03/10/06 21:40

だからソースも仕様書の一部だと思えば良いってこと。（そのソースで生成
されたコードは売り物にならないと思うべきだが）
というか、大抵の場合、日常語で書かれた仕様書というのは、多かれ少なかれ
顧客の業務の重要な情報を含むことが多いわけで、書かれたものは基本的に
顧客に返却して管理させるべきもので、それをどこの馬の骨ともわからない
人間に見せてダイレクトにコード化させることが犯罪的なんだよ。
まだ良心的な会社は、それじゃまずいから、意図的にコーディング上重要な
情報を小出しにし過ぎる。実装不能な仕様を渡されてそれをコード屋のせいに
する。丁度中間のバッファが必要なわけだ。少なくとも実動作する程度のもの
を作って、その中で守秘義務上、伏せておきたい情報を隠蔽すればいいわけだ。
論理的に数分割して時間差をつけて別会社に発注するだけで情報漏洩はかなり
防げる。

28 ：デフォルトの名無しさん：03/10/06 21:45

25==27?
論理設計書、物理設計書
外部設計書、内部設計書
基本設計書、詳細設計書
システム設計書、プログラム設計書

呼び方はいろいろだが、いったいどのレベルの設計書の話をしてるんだ？

29 ：デフォルトの名無しさん：03/10/07 05:47

構想書・提案書・稟議書：漠然としたアイデア。Power-PointやFlash-Animation
とかを使ってイメージを表現すればよい。

計画書：アイデアを前向きに検討する時に作成される。論理的に矛盾が無いか
算術的に不可能ではないか、統計的パラメータの準備は十分か、検証される。
体系的でなく、断片的なものの集積。
Word（論理的妥当性）/Excel（算術的妥当性）/Access（統計的妥当性を使
って書かれる。決してこの段階では仕様書とは呼ばない筈であるが、何故か
この国では仕様書と呼ばれる。

設計書：基本計画がまとまった後、上記計画書群をもとにそれらをつなぎあわせて
一枚の設計書にする。この際に厳格なライブラリを持った言語が好ましいことは
言うまでも無い。.NETやJava等が適している。仮想マシン上で正常動作すること
が大前提。しかし、設計書が完成してもまだ実装段階ではない。
＋αが重要。
＋αとは、プログラムに含まれているパラメータに調整要素をつけること。その
調整要素に優先順位を指定すること。これを行う為には熟練が必要。
この調整パラメータを含んだ設計書が規格書。

実際のコーディングは規格書に基づいて行われるべきである。しかし実装段階
では、調整パラメータを利用した修正が不可避的に必要。（ロジックやアルゴリ
ズムの修正は余りない。環境固有の要素やハードウェアの物理的側面から多少の
変更はあるが、パラメータ修正に較べれば小さい）パラメータ変更は上流に
フィードバックされ、規格書の変更を余儀なくさせる。
これを繰り返して、規格書が仕様書に近付いていく。

結論：
仕様書が出来る前に必ずブツが出来る。
いきなり仕様書を書ける奴は神。

30 ：デフォルトの名無しさん：03/10/07 10:16

>>29
「規格書」とはなんしょうか？その説明が無いので、あなたのいう「仕様書」がなんなのか
よくわかりません。

それから普通は「構想書・提案書・稟議書」と「計画書」の間になにかあると思います。
日本語では『要求仕様書』、アメリカでもrequirement specificationと言うと思います。

31 ：デフォルトの名無しさん：03/10/07 10:18

>>30
あ、すみません。規格書の説明はありましたね。第一パラグラフは取り消します。

32 ：デフォルトの名無しさん：03/10/07 10:22

ところで、ワインバーグも『要求仕様の探求学』という書籍を出しているのをみると
わかるとおもいますが、システムを作る入り口となるものは「要求仕様」であり、
それを書類にしたものが要求仕様書で、この位置づけの仕様書が無いとシステムが
作れないと思います。

33 ：デフォルトの名無しさん：03/10/07 10:45

>>29
どの分野の人？
パッケージ？ゲーム？情シスの人？

34 ：デフォルトの名無しさん：03/10/08 20:54

総合計画書を作るまでは、期待と夢が膨らんでいく段階。この段階は要求定義書
とは言わず、計画書群の一部だろな。
ただ総合計画書を作る段階でどんどん要求が絞り込まれていく。
これは予算とか工期などの生臭い要求も関係してくるというか、殆どの場合
がそれ。この過程でそれまでの前向きな基調だった計画書群とは異なって
やや後ろ向きな要求定義書と呼ばれるバージョンが出てくる。総合計画書
を作る段階では意外に高い影響力を持つ。だから計画書を書かされた人間は
要求定義書を書いた奴を内心憎んだりする。
なお、総合計画書を書く段階で、実装には無関係という前提のもとで、
一応完結的なアプリケーションの形にしても良い。（勿論ソースも残す）
かなり細かい部分まで記述可能な例えばDelphi等を使うと良い。Delphiは
総合計画書を書く段階で最も活躍する言語かも知れない。（但し長期的に
使うのには色々と問題があるので、継続的に使用してはならないと思うべ
きだが）これは企画書を書く段階の助けになるからである。

35 ：デフォルトの名無しさん：03/10/08 23:01

なんかこの長文書いてる人、違う世界の人みたい。

36 ：デフォルトの名無しさん：03/10/08 23:48

読みにくいなぁ。才能無さげ。

37 ：デフォルトの名無しさん：03/10/09 06:13

漢字が多い文章も考えものだと34を見てｵﾓ-ﾀ

38 ：デフォルトの名無しさん：03/10/09 07:29

GUIなんかは、直感でわかるだろ。

D'ont　think feel!

39 ：デフォルトの名無しさん：03/10/09 07:53

誰か34を読める文章に書き換えれ

40 ：デフォルトの名無しさん：03/10/09 08:00

> D'ont　think feel!
何語ですか？

41 ：デフォルトの名無しさん：03/10/09 08:08

>>39 書き換えてみますた。
総合計画書を作るまでは夢。要求定義書はなんつうかもう空絵事。
総合計画書を作る段階でどんどん退化。
生臭い要求も関係してくる。この過程で夢は消える。
要求定義書は、総合計画書を作るときやけに高い影響力を持つ。
だから計画書を書かされた人間は
要求定義書を書いた奴を脳内でぶちのめす。(-_-#)< FackYou!
総合計画書を書くときDelphiでプロトタイプ作っても良さげ。
(ただしそのまま開発にDelphi使うと問題が多発するという諸刃の剣)
まあ、企画書を書く段階の助けにはなるだろうってこった。

42 ：デフォルトの名無しさん：03/10/09 12:09

Delpiでは持続的開発は難しいだろな。
瞬間的に巨大なものを作るのは得意かも知れないが。

43 ：デフォルトの名無しさん：03/10/09 20:02

44 ：デフォルトの名無しさん：03/10/10 06:52

そんな、持続的に長期手直しがあるのが判ってるなら
スクリプトを導入すればいいのに。
ちょっと直す都度コンパイラのコードに手を入れるなんて・・・まるでCOBOLだ。

45 ：デフォルトの名無しさん：03/10/10 16:37

Script言語のような「軽い」言語を動かせる環境は、UnixのShellとか
Web-browserだとか非常に永続性の高い重く巨大で安定した土台がある
からこそ動くわけ。
この土台を構築するのには膨大な金がかかっている。（見た目そっくりなものは
簡単に作れるが）
Script言語を動かしても壊れない土台は実はそう短い時間じゃ作れない。
あと、こういった安定土台＋Script＝理想と考えるのは間違い。
重く巨大な土台が影響して、実は本当に大きな環境激変に耐えられなかったり
する。（ちょっとした変化なら、他よりも非常に巧く対応するが）

46 ：デフォルトの名無しさん：03/10/10 18:36

>>44
いやスクリプトといっても有名所の肥大化したものじゃなくて
せいぜい5千行くらいで書けるような小さなものでも結構役立つよ。
自分は色々作ってやってる。テキストをそのまま実行するものと
もう少し速度が必要な用に中間言語型の２つね。
さっきも仕様変更のメール来たけど、スクリプトの部分だけ変更してメールで送った所だ。

Delphiはバリアント型があるのと、実行時型情報のおかげでスクリプトが簡単に作れて組み込めるのがありがたい。

47 ：デフォルトの名無しさん：03/10/11 15:41

Web-browserっていわいるIEなどの、ブラウザのことですか？

48 ：デフォルトの名無しさん：03/10/14 07:54

ハードウェアがあって、CPUを組み合わせてシステムを作る。
ＯＳが必要になり、ＯＳ固有のライブラリでアプリを作る。
優秀なアプリの上にスクリプト言語やマクロ言語が発生し
やがてそのアプリはＯＳのサブ環境に近づいていく。
スクリプト言語もやがてライブラリが整理され、文法も
補われて単なる言語になる。その言語で書かれたアプリが
再び環境となって....
こうして、ＯＳの上にＯＳが出来てさらにその上にＯＳが
出来るという無限連鎖が発生するように見える。ＣＰＵの
スピードアップはそれを普通に可能にする。
ただこういうのを砂上の楼閣というんだろうね。最終的に
使うのは人だから、上が崩れると下まで巻き込んで、すべて
崩れてしまう。その危険性を日頃から意識しているかいないかで
長期的にみてぜんぜん違ってくる。

49 ：デフォルトの名無しさん：03/10/14 09:52

発生しないよ。

50 ：デフォルトの名無しさん：03/10/14 23:34

要するにそのうちJavaと.NET両方で動く言語ができるってことでつか？

51 ：デフォルトの名無しさん：03/10/14 23:37

J#とJavaでJavaはすでに両方で動いてますね。

52 ：デフォルトの名無しさん：03/10/15 01:12

C#もJVMで動くのかな？

53 ：デフォルトの名無しさん：03/10/15 01:21

>>51
ライブラリが違いすぎ。
言語仕様なんてライブラリに比べたら問題にならないでしょ。

54 ：デフォルトの名無しさん：03/10/15 01:22

どうせクラス仕様書なんか作っても、素人の客は理解なんかできないだろ。
適当でいいんだよ。

55 ：デフォルトの名無しさん：03/10/16 03:25

少なくともJavaで書かれたソースコードは、これは「ソフトウェア」じゃ
ない。「ダイアモンドウェア」であってハードウェアよりもず～っと硬い。
これを現実のハードに適用するとどういう結果を招くか。つまりJavaで
書かれたソースはあくまでも実装準備段階で、別にもう一度ソース最初から
書き直さなければならないってことね。真に良いソフトウェアを書く為には
ダイアモンドのように硬いソースが必要だったりすることもあるから
Javaの存在価値はMSが言うほど小さいものではなかったりする。
ただしそれは十分に柔らく書き直してから使うべきだろうけどね。

56 ：デフォルトの名無しさん：03/10/16 03:32

誰か>>55を日本語に直してくれ。

57 ：デフォルトの名無しさん：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 ：デフォルトの名無しさん：03/10/16 17:37

人権尊重の個人主義社会（都会的自由人）　⇔　Ａ型中心の集団主義的村社会（封建的田舎人）

相容れない？

集団主義社会＝北朝鮮、戦前の日本。

http://www.pref.aichi.jp/jinken/century01.html 　
「人権の世紀」という言葉を聞いたことがありますか？

労働相談・ご意見
http://www.jtuc-rengo.or.jp/new/sodan/mail/rodo_sodan.html

61 ：デフォルトの名無しさん：03/10/16 17:37

＜血液型Ａ型の一般的な特徴（改訂版）＞（「自分だけいい子」は直そう！）
●とにかく臆病・神経質で気が小さいだけ（真に他人を思いやる気持ちには欠けている、二言目には「世間」(「世間」と言っても、一部のＡ型を中心とした一部の人間の動向に過ぎない））。
●異常に他人に干渉して自分たちの古いシキタリを押し付け、そこから少しでも外れる奴に対しては好戦的でファイト満々な態度をとり、かなりキモイ（偏狭、自己中心、硬直的でデリカシーがない）。
●妙に気位が高く、自分が馬鹿にされるとカッと怒るくせに平気で他人を馬鹿にしようとする（ただし、相手を表面的・形式的にしか判断できず(早合点・誤解の名人)、内面的・実質的には負けていることが多い）。
●基本的に悲観主義でマイナス思考なため性格が鬱陶しい（根暗・陰気)。
●とにかく否定的でうざく、粗探しだけは名人級（例え10の長所があっても褒めることをせず、たった１つの欠点を見つけては貶す）。
●社会的強者には平身低頭だが、社会的弱者に対しては八つ当たり等していじめる（強い者にはへつらい、弱い者に対してはいじめる(人が見ていないときは、より一層））。
●少数派の異質・異文化を理解しようとせず、あるいは理解を示さず、排斥する(多数派＝正しい　と信じて疑わない、了見が狭い差別主義者）。
●何でも「右へ習え」で、単独では何もできない（群れでしか行動できないヘタレ）。そのくせ、集団によるいじめのリーダーとなり皆を先導する（陰湿かつ陰険で狡猾）。
●他人の悪口・陰口を非常に好むと同時に、自分は他人からどう見られているか、人の目を異常に気にする（自分がウソツキだから他人のことも容易に信用できない、ポーズだけで中身を伴っていない）。
●友人関係は、表面的な浅い付き合いでしかなく、心の友はおらず孤独（他人の痛みがわからず、包容力がなく、冷酷だから）。
●頭が硬く融通が利かないため、すぐにストレスを溜め、また短気で、すぐに爆発させる（不合理な馬鹿）。
●後で自分の誤りに気づいた場合でも、素直に謝れず強引に筋を通そうとし、こじつけの言い訳ばかりする（社会悪の根源、もう腹を切るしかないだろう！)。
●男は、女々しいあるいは女の腐ったみたいな考え(例：「あいつより俺のほうが男前やのに、なんでやねん！（あいつの足を引っ張ってやる！！）」）。

62 ：デフォルトの名無しさん：03/10/16 17:51

仕様書候補と実装ソースは互いに尊重しあって、相互にそれを修正し
ていって成長するもの。仕様書候補を書こうというものは実装ソース
を書く人のニーズを真に理解していなければならないし、実装者も
仕様書候補の行間を読んで真に必要とされているものを生かしていか
なければならない。
最初に完成された仕様書があって環境毎に異なるバリエーションを持
ちえるプログラムコードはそれに従属し翻訳されたものであるという
考え方は最終的な結果論であり理想論。
というか、その状態になって初めて「仮想原本」たる仕様書と呼べる
水準のものになる。この仕様書の価値こそが極めて高いわけで、これ
が生まれることをほのかに期待するからこそ人はプログラムという邪
道に敢えて入り込むわけ。
ダイヤモンドを散りばめた服が、決して服の究極の代表的な姿にはな
りえないのと同じように、ソフトウェアも硬く鋭く光る部品で構成
されているものが終局的な姿だというわけでもないだろうね。
ま、一度その方向に極端化してみる（洗練と人は言う）というのはそ
れはそれでいて得られるものは大きく貴重なものも多いのだろうが。

63 ：デフォルトの名無しさん：03/10/16 18:26

↑文章が下手糞では説得力も糞もない

64 ：デフォルトの名無しさん：03/10/16 23:03

>>62
ちゅーか、ながい。
沢村の友達なんだ炉。

65 ：デフォルトの名無しさん：03/10/16 23:18

>>62は>>55だろ

66 ：デフォルトの名無しさん：03/10/16 23:26

ダイヤモンド大好きっ子ですね

67 ：(゜Jし゜）：03/10/16 23:27

ソースとドキュメントの一致と言う意味では、詳細設計レベルでは
JavaDocみたいなのを使うのが一番だよね。
概要設計レベルならUMLになるのかな？

でも、どっちも理解してくれないウチのPM…
まぁ何を書いても突っ返される訳だが（工数稼ぎのため？）

68 ：デフォルトの名無しさん：03/10/17 02:15

doxygen とかで（規約かなんかで）全ての関数インターフェースに
コメントをつけるとしたとき、仮引数名がその意味を完全に表していたときは
１．書かない
　→UNDOCUMENTEDの警告がいつも出てしまってほかの警告が霞んでしまう
２．繰り返す：@param instance インスタンス
　→かっこわるい
３．空にする：@param instance
　→まちがってる気がする
どれがいいんでしょうか？

69 ：デフォルトの名無しさん：03/10/17 06:49

「XXXのインスタンス」とか書くのはだめなの？

70 ：デフォルトの名無しさん：03/10/17 10:40

>>68
2

71 ：デフォルトの名無しさん：03/10/17 10:58

>>68
４．決めうち：@param instance ソース嫁

72 ：デフォルトの名無しさん：03/10/17 20:37

ドキュメント：
自分たちが書くべき言語で書かれた文書のこと。
それを読んで次の工程の人がその人たちが書くべき言語でコードを書く。
C言語で書かれたドキュメントをコンパイラに渡してそれを参考に
アセンブリコード或いは機械語コードに変換する作業をコンパイルと呼び
その作業をする人或いはソフトウェアをコンパイラと呼ぶ。

ソース：自分たちよりも前の工程の人が書いたドキュメント群のことを区別
する為にソースと呼ぶことが多い。
Javaでドキュメントを書いている人たちも、日本語のソースや英語のソース
を読んで書いている場合が多い。多くの場合、それは既にオンライン化され
ている場合が多く、Word・Excel等の上で読めるものであったりすることが多
い。

コード：自分たちの次以降の工程の人が書く文書はコードと呼ぶ。

73 ：デフォルトの名無しさん：03/10/18 23:25

良いドキュメント・マニュアル・仕様書は、

良い会社・環境・人間関係という土台があってこそ

（続きどうぞ

74 ：デフォルトの名無しさん：03/10/19 05:22

●●●マスコミの「盗聴／盗撮」は許されるの？その５●●● http://natto.2ch.net/mass/kako/998/998142751.html
724 名前：文責：名無しさん投稿日： 01/09/09 17:52 ID:Na9tEsUs
>>722
＞早朝番組の「占いコーナー」なんて、個人向けメッセージの宝庫かもしれないですね。
雑誌の占い欄もそうですね、以前も書いたけど。
「あなたの成果を横取りする人がでてくるかもしれません。その人の要領の良さに嫉妬しないで」
というアドバイスをある占いから頂きました。でも残念ながら，盗聴の要領の良さは嫉妬の対象になりません。
それに、成果を横取りするよりも、私にとっては、私生活の侵害のほうが遥かに腹立たしいです。

> 口では「マスコミの盗聴」に反対しながら、本音の部分では喜んでるんだろ、と思っている。
だから、盗聴に対する罪悪感がないのだ。その根底にあるのは、
女子アナ・芸能人というものに特別の価値があるという自惚れだ。

あはは、なるほど。そう言えば、盗聴やストーキング行為は、
かっこいい人にならされてもいいと言った、某マスコミ関係者がいたらしい。
された事ないから、わからないんだよね。それを聞いた人が
「なんだ、盗聴されても悪い気はしないんだ」と思い、罪悪感無く盗聴を続ける事になる。
いくら尊敬している人でも、かっこよくても（笑盗聴がわかった時点で、信用は無くなります。

75 ：デフォルトの名無しさん：03/10/19 06:21

♥

76 ：デフォルトの名無しさん：03/10/21 01:17

えーと、仕様書ってのは客に見せるもんなのか
客が読んで役に立つのは要求仕様と運用マニュアルでは･･･
つーか、運用マニュアルって作んないのか･･･

77 ：デフォルトの名無しさん：03/10/21 07:57

俺もそう思う、実際見てくれたことないし。
仕様書ってのは何年後かに変更が発生した場合
自分たち（もしくはその修正を行う別会社）がどういう仕様か
確認するものだとおもてるよ

78 ：デフォルトの名無しさん：03/10/21 17:33

何年後っておまえ・・

79 ：デフォルトの名無しさん：03/10/21 22:25

このスレの文章読みづらいにだけど。

80 ：デフォルトの名無しさん：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 ：デフォルトの名無しさん：03/10/25 09:35

ソースコードをハイパーテキスト化しよう。

86 ：(゜Jし゜）：03/10/25 10:36

で、ドキュメント作成する時間を取れなかったので、
コメントに詳細仕様を記述しておいたので、後で暇人を
使ってコメントから仕様書を起草しましょう、と言ったところ、

「結局、ソースを読め！かよ。これだからPGは自分勝手な…」
「ドキュメントきちんと作って…困るんだよねぇ…云々｣

PMさん…コメントと自動生成のリファレンスだけでいいんです…。
ほんとに仕様書書く時間無いんですよ、助けてください。

87 ：デフォルトの名無しさん：03/10/25 12:19

そのＰＭにケント・ベックの本でもプレゼントして差し上げましょう。
「今時不勉強なＰＭは生き残れませんよ」って。

88 ：デフォルトの名無しさん：03/10/25 13:07

ケント・ベックは、要求されるなら仕様書書けっていってるぞ。

89 ：デフォルトの名無しさん：03/10/25 13:08

doxygenで任意の単語にリンク張りたいんだけど、
\anchorや\refいっこいっこ付ける方法しかないですか？

90 ：デフォルトの名無しさん：03/10/25 16:14

設計書と一言で言っても分野や会社によってルールも書き方もまちまちとは思う。書く場合も書かない場合もあるだろう。
本質的には「どんな書類」が「いつ・どの期間」「誰に対して」必要なのかを明確にしておく必要があると思うのだ。

・外部仕様書
　大抵の職業PG,SEはある程度規模が大きいソフトウェアを作るだろうから，少なくともマニュアルに近いもの，
　一般的にはもっと詳細なものを最初に作るはずだと思う。
　更に言えば，殆どの奴らは既存システムの改善（保守）をやっているので，既存の操作の変更があれば，最初に
　どことどこを変更って決めたものを書いておかないとユーザ（またはマニュアル部隊）が困るはず。
　ユーザに渡す前なら作った後でも良いし，正直最後に微修正が入ることもあるとは思う。
　昔ユーザに「ソース読めば？」って言ったプログラマが居たが喧嘩になったよ。もうアホかと…

・詳細設計書
　将来の誰かに対して残しておくってこともあるだろうけど，どこをどう直したかを書類としてのこしておかないと
　ビルダー（パッケージング）する奴が困ると思うぞ。ちゃんとしたSEなら，どこを直したのか把握して全体の
　調整もするはずだ。馬鹿SEも多いが，そういう書類を作って公開しておけば隣近所の奴が何やっているのかも
　分かるしね。ソースから読めって奴もいるだろうけど，STABLE な状態ばっかりで開発できる羨ましい環境で
　生活してんだなと思うぞ。

んじゃ。

91 ：デフォルトの名無しさん：03/10/25 16:59

>>90
すんごいローカル定義だこと。

92 ：(゜Jし゜）：03/10/26 11:50

ちなみにそのプロジェクト、外部仕様書は件の暇人を使って
書かせていたのでユーザには迷惑は掛かりませんでしたが…。
そしてそのPMは寄寓にもジャスト35歳だったりして。

結局、自分で書きましたよ、ええ。
後でメンテする人が困るし。

93 ：デフォルトの名無しさん：03/10/26 12:20

>>92
きみが書いた仕様書は、誰も解読できないと思うけどね・・・

94 ：(゜Jし゜）：03/10/26 23:59

>>93
痛いところを突きますね。
確かに自分の書いた仕様書は自分用のメモみたいな程度のもんでした。
でもまぁ無いよりはましかな、とか思ったもので…。

まーその辺の現実に目を背けたくてこんなスレにいるわけですが。

95 ：デフォルトの名無しさん：03/10/27 13:04

自分はＳＥではなくプログラマーなのですが
プログラマーとしてドキュメントはどんなものを書いていますか？

ウチは外注のソフトハウスで
ＰＭ・ＳＥは元請け会社がやっています。
元請け会社が作った、基本仕様書（仕様書とは名ばかりで、機能が羅列して書いてあるだけ）
を元にプログラムを書くのが
我々の仕事なのですが、

元請け会社に提出用のドキュメントや、
社内の人間に、自分が休んだり辞めたりした後に
他の人でも対応して貰えるように残しておくドキュメントとして
どんなものを作って（書いて）いますか。

ちなみに、今、私は一太郎でドキュメントをシコタマ書いていますが
ドキュメントを書く便利なツールやソフトって無いですか？

96 ：デフォルトの名無しさん：03/10/27 13:18

DBから吸い出せば一発で分かるテーブルレイアウト図なんかいりません。
ER図(これもツールで吸いだせるケース多し)と、DFDだけは残してください。
全文検索に引っかかりにくく死蔵になりやすいOffice文書も正直ｲﾔです。

97 ：95：03/10/27 13:21

ちなみにウチの会社
ドキュメントの作成が、みんなマチマチで
ロクなドキュメントを残さないので、
「作った本人しかわかりません、触れません」状態になっており
休みの日にドラブルが起きると
家や携帯に電話が入る。

おちおち、休んでもいられない
杜撰な会社です

98 ：デフォルトの名無しさん：03/10/28 03:47

そういや、いくらがんばってドキュメント書いても、誰も読まずに聞いてくる。

99 ：デフォルトの名無しさん：03/10/28 09:49

>>98
それはロクなドキュメントじゃないから。

100 ：デフォルトの名無しさん：03/10/28 09:51

>>96
テーブルレイアウト図（って何だ？）を見たいと思った人間が、いちいちDBから吸いださずに
すむという理由で、テーブルレイアウト図（って何だ？）は存在しておいたほうがよい。

101 ：デフォルトの名無しさん：03/10/28 09:52

>>96
Office文書がいやなら当然PDFもいやなんだろうが、だとするといったい何で書けと？

102 ：デフォルトの名無しさん：03/10/28 10:49

>100
DBのテーブル毎にカラム名やキー、制約なんかを記述したドキュメントの事だけど。
テーブルレイアウトって言わない？これってローカル語なのか…ｽﾏｿ一般的には何て言うの?
DBからの吸出しは事実上ワンクリックで済む以上、手間では無いと思っているのだが・・・

>96
プレーンテキスト。あとはWikiかな。
もちろん、テキストだけで表現できない要素ならそれにはこだわりません。
OfficeやPDFだとどうしても見栄え的な部分へ力を割かなきゃいかんし更新の際に差分を
残しにくいのものも嫌いな理由の一つ。
あくまでも、内部用ドキュメントの話ね。外部に出すならワープロで作るのは構わないと思う。

103 ：デフォルトの名無しさん：03/10/28 11:31

どうせおまいら"理科系の作文技術"すら読んでないんだろ？

104 ：デフォルトの名無しさん：03/10/28 18:17

>>99
読んでないのにろくなドキュメントかどうか分かるわけないだろう

105 ：デフォルトの名無しさん：03/10/28 18:50

読まれないということはロクなドキュメントじゃないからだって事でわ?

106 ：デフォルトの名無しさん：03/10/28 19:34

>>105
>>104

107 ：デフォルトの名無しさん：03/10/28 21:41

まーふぃーの法則。
誰も読まないからドキュメントを書かないでいると、必ずドキュメントを要求される。

108 ：デフォルトの名無しさん：03/10/28 21:49

補足：
書くと今度は誰も読まない。

109 ：デフォルトの名無しさん：03/10/28 22:16

>>102
> >100
> DBのテーブル毎にカラム名やキー、制約なんかを記述したドキュメントの事だけど。
> テーブルレイアウトって言わない？これってローカル語なのか…ｽﾏｿ一般的には何て言うの?
> DBからの吸出しは事実上ワンクリックで済む以上、手間では無いと思っているのだが・・・

ファイルとして保存しておけば、1秒もかからずに誰でも見始めることができるのだが。

> >96
> プレーンテキスト。あとはWikiかな。
> もちろん、テキストだけで表現できない要素ならそれにはこだわりません。
> OfficeやPDFだとどうしても見栄え的な部分へ力を割かなきゃいかんし更新の際に差分を
> 残しにくいのものも嫌いな理由の一つ。
> あくまでも、内部用ドキュメントの話ね。外部に出すならワープロで作るのは構わないと思う。

たぶんOfficeの使い方を間違っている。というか使いこなしていない。
Wikiで書いた文章を配布するときはどうするんだ？HTMLで配布するのか？

110 ：デフォルトの名無しさん：03/10/29 09:04

>109
そのファイルが現物のDBを反映した物である保証があるならそれもアリですな。

>96
Officeに文書のバージョン管理の機能ってあるの?
是非教えてくれ。Officeを好きになれるかも。
配布に関しては別の話になると思うのだが・・・
まぁHTMLに吐くのもアリだしWikiによってはそのままPDF吐いてくれる物もあるし。

んで「テーブルレイアウト図」は一般的なんでしょうか。
気になって夜も眠れません・・・

111 ：デフォルトの名無しさん：03/10/29 10:43

>>110
ぐぐってみりゃわかるだろうが。

日本語のページからテーブルレイアウト図を検索しました。約6件中1 - 4件目・検索にかかった時間0.21秒

普通は「テーブルレイアウト」という。

112 ：デフォルトの名無しさん：03/10/29 21:57

>>110
>Officeに文書のバージョン管理の機能ってあるの?
少なくともWordにはある。

が、ファイルがどんどん肥大化するのでお薦めできない

113 ：デフォルトの名無しさん：03/10/29 22:01

Wordでどうやんの？

114 ：デフォルトの名無しさん：03/10/30 00:25

制御系のプログラマの場合、
開発した後、どんなドキュメントを残しますか？

115 ：デフォルトの名無しさん：03/10/30 00:28

>>110
カラムの名称や型や制約に関する記述はスキーマとかテーブル定義書って言うんじゃ
なかったっけ。テーブル間の関連を図示したものはＥＲＤだな。

116 ：110：03/10/30 08:45

>111
あ、そういう事か。
図を抜く訳ね。
てっきり「一般的にはみかんと呼ばれる物を俺のところではりんごと呼んでいた」
くらい違うのかと思ってた。
今後気をつける。

117 ：デフォルトの名無しさん：03/10/30 10:00

>>114
当然相手に応じて。

言われなければ俺は
回路図とかの図面はPDFにして
テキストで書ける事は全部ソースに全部埋め込む。

118 ：112：03/10/30 22:22

>>113
どうやんのって、持ってるならヘルプ見れよ！！！
今回だけだぞ、
[ファイル]－[版の管理...]

119 ：デフォルトの名無しさん：03/10/31 01:07

ドキュメントのメンテ工数もらえないうちらはどうすればよいでしょうか

120 ：デフォルトの名無しさん：03/10/31 12:07

その分別工程に上乗せ。

121 ：デフォルトの名無しさん：03/11/21 23:23

Doxygen Release 1.3.5 age

122 ：デフォルトの名無しさん：03/11/22 13:45

DoxygenでXHTMLを吐く上手い方法はないかね？

123 ：デフォルトの名無しさん：03/11/22 17:58

Doxygenの出力パーサを弄くるとか。
あれってC++だっけ？
Doxygenレベルのlexerが単体で使えれば楽になることが沢山あるんだが・・。

124 ：デフォルトの名無しさん：04/02/17 16:19

仕様書ってーか、目論見書つくらんといけなかったのですが、
windowsのアプリ完成後のイメージを作成するのに、
簡単にコントロールぺタぺタできるのありませんかね？
ＶＣのダイアログボックスも、ＶＢのダイアログボックスもめんどくさいとこあるし・・・。
どなたか良いのありましたら教えてください。

125 ：デフォルトの名無しさん：04/02/18 00:59

目論見書って、金融の目論見書しか知らないんだけど。

その目論見書？
それにWindows の UI を乗せる必要がある？

126 ：デフォルトの名無しさん：04/02/18 09:21

>>125
レスありがとうございます。

なんつーんでしょうかね？まぁ、こんなん作りますがみたいなのを他社に送るもんらしいです。
まぁ、中身も当然ですがＵＩの使いかってがかなり重要っぽいので・・・。
もう、フリーハンドでもいいとおもうんですけどね・・・。
とりあえず、今回はまぁそれなりに書いたんでどね。
次回以降ワードあたりでしこしこ線引くのも疲れるんで、なんか楽なの無いかな？と思いまして・・・。

127 ：デフォルトの名無しさん：04/02/18 20:18

Visioなら書けるが、VC・VBの方が楽。よってVisioでは無理。

128 ：デフォルトの名無しさん：04/02/18 21:45

>>127
wxWindowsのGUIツールキットBOAとかFOXとかFLTKあたりで作成できないもんかと思って、
とりあえず、暇できたらなんか色々チャレンジしてみます。
でも、.NET対応流行ったらどうすっぺ・・・。

129 ：デフォルトの名無しさん：04/02/18 22:36

FLTKは日本語まわりがアレ、wxWindowはちょっとDLLがデカイ
gtk+ 導入するのにものすごい壁がある。 Foxは知らん。
なんとなく実用的なものならwxWindowがいい、
でもどれでもポトペタは無理だと思う。

130 ：デフォルトの名無しさん：04/02/18 22:44

ポトペタってなに？

131 ：デフォルトの名無しさん：04/02/18 23:15

>>126
俺の会社の先輩はPowerPoint使ってデモしてました。
文字入力画面はできない(アニメーションでやってた)みたいだけど、
ボタンと画面表示はリンクで適当に作ってました。
全画面表示のアプリで、それっぽく見せてましたよ。

132 ：デフォルトの名無しさん：04/02/18 23:42

まぁVBが一番楽なんだろうね。

133 ：デフォルトの名無しさん：04/02/19 01:56

画面設計書じゃないから、それこそ"○○部分"と書いた枠の配置だけでいいと思う。
というか、そうでもして抽象化しないと完成画面だと思われる。

はっきりいえば、Windows の画面かどうかも分からないように書いたほうがいい。

134 ：デフォルトの名無しさん：04/02/19 06:20

もしもしTcl/Tkを忘れてますよ

135 ：124：04/02/19 09:35

>>129-134
みなさまどーもありとうございます。

>>129,132
ポトペタ（ポトッとおとしてペたって貼り付け？）は無理ですか。
ＶＢで適当につくるのがいいんですかね・・・。
でもおいらＶＢ苦手っす（なんかめんどいからかな？）。
超初心者用ページでいいページないですかね（スレ違い）。
C++ならそれなりにモウマンタイって感じなんですけど。

>>131
パワーポイントっすか。使ったことないですね。考慮してみます。

>>133
うーむ、画面設計書とかそこらへんの違いよくわからないです。
そういうのわかる書籍とかページありませんか？（スレ違い？）
とりあえず、今度は抽象化してだしてみますね。

>>134
あ、どもです。とあるページに載ってなかったもんでメジャーではないのかと思いまして。
（ここのＧＵＩスレには載ってますけど）

136 ：デフォルトの名無しさん：04/02/26 23:15

末端プログラマしかやったことないんですが、
ちょっとＰＭで設計書の類（まだはっきりしてないけど）を書く必要にせまられました。

で、役立つオススメな本あります？

137 ：デフォルトの名無しさん：04/02/27 22:42

まず、身の周りに先輩達が書いた設計書(見本)がないか探してみる。
なかったり、どうしようもないような代物なら…ガンガレ。

プログラム設計書　でぐぐると合うような物が見つかるかもよ。

138 ：デフォルトの名無しさん：04/02/27 22:47

周りに先輩達が書いた設計書(見本)がないか探してみる。
なかったり、どうしようもない代物だったら…ガンガレ。

プログラム設計書でぐぐる
要求定義からやる羽目になる罠もあるのでその辺もひっかけておく。

139 ：デフォルトの名無しさん：04/02/27 22:50

二重カキコ。逝って(ry
＿|￣|○

140 ：(゜Jし゜）：04/02/27 23:55

http://www.seshop.com/detail.asp?pid=4448

このへんどうよ？

141 ：136：04/02/28 05:24

>>137-139
ありがとうございます。あさってみます。

>>140
ありがとうございます。アキバのラオックスで立ち読みして、よさそうならかってきます。

142 ：http://bulkfeeds.net/app/search2?q=UML：04/03/31 00:03

UML・仕様書・設計書関連2chスレッドのまとめ　（siyousyo - wikich）

http://pwiki.chbox.com/pukiwiki.php?siyousyo

http://bulkfeeds.net/app/search2?q=UML

143 ：デフォルトの名無しさん：04/05/11 00:16

doxygen 1.3.7 age

144 ：デフォルトの名無しさん：04/07/18 17:51

詳細設計書は、プログラム処理の羅列でいいんだよね？

145 ：デフォルトの名無しさん：04/07/20 02:43

>プログラム処理の羅列

ダメ、それはプログラム設計書だNe!

146 ：デフォルトの名無しさん：04/07/25 19:54

doxygen 1.3.8 age

147 ：デフォルトの名無しさん：04/09/11 00:13:39

142さんありがとうございます。助かりました。
激遅レスだけど、感謝です。

148 ：あげ：04/09/25 05:02:40

doxygenで複数の言語向けのドキュメントを書くにはどうすればよいのだろう？

149 ：デフォルトの名無しさん：04/09/25 05:06:02

http://www.npb.or.jp/

150 ：148：04/09/25 05:09:09

すまん。
doxygen+"two languages"でぐぐったらマニュアルの\ifディレクティブの項に書いてある事が分かった。

151 ：デフォルトの名無しさん：04/09/28 16:09:35

保守

152 ：デフォルトの名無しさん：04/10/06 23:25:55

運用マニュアルや仕様書だの、どこか公的な書き方の決まりはあるんでしょうか。
例えばメニュー名などはどういう括弧でくくるのか、単語末の長音はない
方がいいとか、会社とかによってルールとかはあるとは思うんですが…。
でもまちまちだとどこか新しい営業先に提案書持っていくときだの、いろんな
会社のマニュアルを保管する側とかとまどったりするんじゃないかと
思うのですが、みなさんは普通に自分の周辺ルールで書いてますか？

153 ：デフォルトの名無しさん：04/10/07 01:12:28

doxygen 1.3.9 age

154 ：デフォルトの名無しさん：04/10/07 01:18:23

>>152
今までマニュアルや仕様書を（良い悪いに関わらず）読んできた経験に基づいて決める。
どこでも見かけるルールには従う。
あ、このルールいいな、と思ったものは取り入れてみる。
このルールだめじゃん、と思ったものは自分ではそうならないように気をつける。
ま、毒にも薬にもならん意見だな。

「ドキュメント」「標準」とかをキーに検索すれば？

155 ：デフォルトの名無しさん：04/10/07 23:01:14

俺も結局わからないまま、ウケよかったからいいか…とか
先例でいい奴とかまねしてるが、業界として共通の表現とかって
どっかないんかな…

156 ：デフォルトの名無しさん：04/10/07 23:10:44

この調子ではどうせ読む奴もわからないからいいんじゃない

157 ：デフォルトの名無しさん：04/10/08 06:09:48

どうせ誰も読まないから適当でいいんじゃない

158 ：デフォルトの名無しさん：04/10/13 00:00:55

doxygne 1.3.9.1 age

159 ：デフォルトの名無しさん：04/10/13 01:09:00

doxygenやJavaDocは多言語対応まで視野に含めると、どうかなと思ったり。

160 ：デフォルトの名無しさん：04/10/13 01:58:22

>>159 詳しく

161 ：デフォルトの名無しさん：04/10/13 07:55:33

>>159
INPUT_FILTER使えば？

162 ：デフォルトの名無しさん：04/10/13 17:55:43

俺ぐらいのレベルだと
ソースがドキュメント

163 ：デフォルトの名無しさん：04/10/13 17:56:44

ドキュメントが嘘ついている場合もあるのだ。

164 ：デフォルトの名無しさん：04/10/13 21:45:34

>>162のソースは嘘をついている

165 ：デフォルトの名無しさん：04/10/13 21:49:15

ソースがドキュメントと言っている奴のソースは大抵糞。
俺のソースはきれいだと腐ったソースで自分に酔ってる厨と同じ。

166 ：デフォルトの名無しさん：04/10/13 22:08:47

腐ったソースで走り出す♪
（プロジェクトが）

167 ：デフォルトの名無しさん：04/10/13 22:33:25

warota

168 ：Ruby!!!!!!!!!!!!!!：04/10/13 22:35:09

まつもとゆきひろ尊師は「ソースがドキュメント。バグもそこに記述されている」と仰いました。
おまえらひれ伏せ。

169 ：デフォルトの名無しさん：04/10/14 00:53:52

#if 0
ドキュメントはソースだけで十分です。
#endif

170 ：デフォルトの名無しさん：04/10/14 11:46:15

×ドキュメントはソースだけで十分です。
○ドキュメントはソースだけしかありません。

171 ：162==163：04/10/15 12:47:21

>>164-166
いや、
おれが、ドキュメント書かないわけじゃないよ。
一応気を使ってdoxygen対応で書いてるぜ。

で、
わかりにくいドキュメント見るぐらいなら、ソース見るって感じ。

ドキュメント読んで信じて、騙されるぐらいなら
ソースを読んだ方が正確。時間もさほど変わらない。←これが俺ぐらいのレベル

ソースが汚い奴のドキュメントは、
やっぱりわかりにくい罠ってのもある。

一応、EffectiveC++レベル以上のその系統の書籍を数冊読んでるし、
汚いソース何個も見てきたので
ある程度の読みやすいソース書く自信あるぜ。
そういう本読んでない初心者ちゃんにはきついかも。

172 ：デフォルトの名無しさん：04/10/15 15:14:32

ソースだけだと仕様なのか脆弱性なのかバグなのか区別がつかん。
ソース自体が読みやすいとか読みにくいとは全く別問題だし。

自分のソースにはバグは一切無いとか、
仕様のためのコードなのか、高速化のためのコードなのか、単にダメっぽいコードなのか、
みたいのを誰が見ても一目瞭然で区別できるとかいうなら話は別だが。

173 ：デフォルトの名無しさん：04/10/17 07:34:17

サルベージ

174 ：デフォルトの名無しさん：04/10/31 22:59:23

ドキュメントがメンテされてなくて役に立たん、というのはよくある話だ。

175 ：デフォルトの名無しさん：04/10/31 23:06:43

ドキュメント更新まで含めてコーディングすればいい

176 ：デフォルトの名無しさん：04/11/03 15:51:12

ドキュメントは古参ＳＥの頭の中だけってプロジェクトもあるよねえ（溜息）

177 ：デフォルトの名無しさん：04/11/23 20:57:53

今日Doxygen使い始めた。教科書はCマガジンの2002/8とDoxygenヘルプ。

*.hにコメント書くよりも*.cppに書いたほうが良い、というのは理解した。
(そりゃそーだわな)

でも、DLLなどのバイナリライブラリでソース見せたくないときは、
*.hに書くしかないような気がする。

*.cppに書いてあったコメントが、あたかも*.hに書いてあったように
Doxygenできる方法ってあるの？

それともローテクにリリース寸前でコメントを*.hにコピペするんか？

178 ：デフォルトの名無しさん：04/11/23 21:01:35

おれ177
まだまだ使い始めだからわかってないのかもしれないが、
要は、ソースが丸見えになるのがいやなのだ。
ソースを隠すオプションが探し切れていないだけなのかもしれん。

179 ：デフォルトの名無しさん：04/11/23 23:23:10

>>177
Doxygenした結果はcppに書いてあろうがhに書いてあろうが同じだと思うが。
ソース隠すオプションはある。

180 ：デフォルトの名無しさん：04/11/24 15:01:58

というかデフォルトで隠されてたような。
WindowsならDoxyWizard使うと楽チン。

181 ：デフォルトの名無しさん：04/11/24 19:01:47

おれ177
すまんかった、いろいろ試してみたらソース隠せたよ。
DoxyWizardは知らんかった、ちょっとさわってみる。

182 ：デフォルトの名無しさん：05/01/03 15:58:41

doxygne 1.4.0 age

183 ：ライブラリアン：05/01/03 16:36:26

ドキュメントってプログラミングする前に
書くものじゃないの。仕様書とか検査成績書とか。
プロはドキュメントを書いている時点で情報不足や矛盾が
わかるのでしょう。
プログラムを作ってからドキュメントを作るのは
最低だな。ゲーム少年の域をこえてないよ。

184 ：デフォルトの名無しさん：05/01/03 18:44:34

cppdocもソースやヘッダーの内容を文書化するのに使える

185 ：デフォルトの名無しさん：05/01/03 19:00:47

>>183 うるせーばか

186 ：デフォルトの名無しさん：05/01/03 21:42:33

>>183は真のゲーム少年

187 ：デフォルトの名無しさん：05/01/03 22:07:53

まず「ゲーム少年」というのが何だかよくわからないな

188 ：デフォルトの名無しさん：05/01/03 23:36:12

>>183
おいらのとこでは、プログラマが書くのは保守ドキュメントのほうが多い。
そうするとあとで書いたほうがいい。
同時にかくのはもっといい。
仕様書、成績書は別の人間が書く。
同じ人間がかくってことは零細？

189 ：デフォルトの名無しさん：05/01/03 23:38:38

零細の何が悪い

190 ：デフォルトの名無しさん：05/01/04 00:00:46

誰が書く、ということではなく
書く順番の話をしているのでは
ということは188は読解力ゼロ？

191 ：デフォルトの名無しさん：05/01/04 01:47:32

属人性MAX

192 ：188：05/01/04 23:28:28

>>190
プログラマの文書は保守文書が多かろうから
あとか同時に書くほうがいいし、あとが駄目とは
言い切れないんじゃないのということが言いたかった
ですよ。
んで、矛盾を見つかる仕様書は別の人が
書くだろうからそれで、非プロとはいかがなものかと。

>>189
悪くないけど大変ですね。

193 ：デフォルトの名無しさん：05/02/08 23:36:23

doxygenのLaTeX出力は鬼門だな

ttp://www.atmarkit.co.jp/bbs/phpBB/viewtopic.php?topic=8354&forum=3&2
この辺のでｻﾝﾌﾟﾙは上手く逝ったが、漏れのソースだとｲﾋけ杉

194 ：デフォルトの名無しさん：05/02/09 15:13:57

要件定義書でのデータモデルって、良いお手本ありますかね？
概念モデルで。

195 ：デフォルトの名無しさん：2005/04/09(土) 19:20:51

doxygen 1.4.2 age

196 ：デフォルトの名無しさん：2005/05/08(日) 01:04:55

doxygenで、ローカル変数のコメントを出力するにはどうすりゃいいんすか？

int main(void){
　char s[BUFSIZE]; //!汎用バッファ
　↑こんなやつ。

197 ：デフォルトの名無しさん：2005/05/08(日) 01:11:53

>>196
ローカル変数を廃止して、全部グローバルにすればOK？

198 ：デフォルトの名無しさん：2005/05/08(日) 01:14:38

http://FLH1Ach124.kng.mesh.ad.jp/
ｗｗｗｗｗｗｗｗｗｗｗｗおｋｗｗｗうはっｗｗｗ
うぇｗｗｗ
おｋｗｗｗっっおｋｗｗｗｗｗｗｗｗｗｗ

ｗｗｗうぇｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗ

199 ：デフォルトの名無しさん：2005/05/08(日) 01:28:10

http://YahooBB219215164084.bbtec.net/
おｋｗｗｗっっおｋｗｗｗっうぇうぇｗｗｗ

うはっｗｗｗ
っｗｗｗｗｗｗｗｗｗｗｗｗ
っうぇｗｗｗｗｗｗ
うはっｗｗｗっうぇｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗ

200 ：デフォルトの名無しさん：2005/05/08(日) 23:37:07

>>196
そんなもの出力する必要あるの？

201 ：デフォルトの名無しさん：2005/05/08(日) 23:48:31

>>200
変数のドキュメントは必要でしょー

202 ：デフォルトの名無しさん：2005/05/08(日) 23:50:12

えーだってローカル変数だよ？
doxygenって、関数やクラスのインタフェースを記述するためのものじゃないの？

203 ：デフォルトの名無しさん：2005/05/09(月) 11:15:06

>>202
きめつけ：(･Ａ･)ｲｸﾅｲ

204 ：デフォルトの名無しさん：2005/05/09(月) 11:27:33

>>203
ローカル変数ってのは隠蔽されるべきものなので、
皆が読むドキュメントには書くべきではないと思われ。

実装者とか保守する人用に注意書き程度にコメント書くなら構わんと思うけど。

205 ：デフォルトの名無しさん：2005/05/09(月) 11:54:51

意味不明文書が大量生産されるのは
じつわ
ぜんぶmadeinusa
なので
それを
にほんごにするときに∞∴♂♀℃￥＄￠￡％＃＆＊＠§☆

206 ：デフォルトの名無しさん：2005/05/09(月) 12:07:04

http://ntchba046149.chba.nt.ftth.ppp.infoweb.ne.jp/

おｋｗｗｗうはっｗｗｗｗｗｗおｋｗｗｗ
ｗｗｗｗｗｗｗｗｗｗｗｗ
っうぇ
ｗｗｗｗｗｗｗｗｗｗｗｗ
うはっｗｗｗおｋｗｗｗｗｗｗｗｗｗｗｗｗｗっうぇ

207 ：デフォルトの名無しさん：2005/05/10(火) 00:19:54

>>204
保守用ドキュメントを作成し

208 ：デフォルトの名無しさん：2005/05/10(火) 02:08:45

>>207
普通は意味無いので

209 ：デフォルトの名無しさん：2005/05/10(火) 02:30:03

http://pl070.nas931.nara.nttpc.ne.jp/
ｗｗｗｗｗｗｗｗｗｗｗｗｗうはっｗｗｗｗｗｗｗｗ

ｗｗｗっｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗ
おｋｗｗｗ
うはっｗｗｗｗｗｗうぇｗｗｗ
ｗｗｗｗｗｗｗｗｗｗｗｗ

210 ：デフォルトの名無しさん：2005/05/10(火) 03:33:47

http://218.33.211.112.eo.eaccess.ne.jp/
おｋｗｗｗうぇｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗうはっｗｗｗ
うぇｗｗｗｗｗうはっｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗ
ｗｗｗｗｗｗｗｗｗｗうはっｗｗｗｗｗｗうぇｗｗｗ

211 ：デフォルトの名無しさん：2005/05/11(水) 08:37:36

↑あげると、こうなるので、上げないように。

212 ：デフォルトの名無しさん：2005/05/11(水) 20:58:44

だが断る

213 ：デフォルトの名無しさん：2005/05/12(木) 09:26:54

だがそれがいい

214 ：デフォルトの名無しさん：2005/05/12(木) 22:50:48

だが断る

215 ：デフォルトの名無しさん：2005/05/13(金) 09:19:26

だがそれがいい

216 ：デフォルトの名無しさん：2005/05/13(金) 18:14:50

俺たちの青春かよ！

217 ：デフォルトの名無しさん：2005/05/15(日) 00:34:54

おまいら、API仕様書とか書くときMS-WORDか？
ソースのひな形つくってdoxygenか？
なんか綺麗な方法ないか探し中の俺に教れろ。

218 ：デフォルトの名無しさん：2005/05/15(日) 01:00:18

>>217 doxygen 使っとけ。

219 ：デフォルトの名無しさん：2005/05/17(火) 01:13:37

doxygen 1.4.3 age

220 ：デフォルトの名無しさん：2005/06/07(火) 00:18:40

doxygen 使っとけ

221 ：デフォルトの名無しさん：2005/06/12(日) 01:55:49

DocBookとかDITAとか使ってる香具師いる？

222 ：デフォルトの名無しさん：2005/06/12(日) 12:15:26

いたらどうなんだよｗ

つーか、いねーよそんな奴(ﾌﾟｹﾞﾜﾛｳｽ

223 ：デフォルトの名無しさん：2005/06/12(日) 14:45:09

WORDで作るWebページって仕様になるのですかな？
目的はdoxygenにリンクさせて、一括管理しようと思ってます。（名づけて一元化）
WORDで作るとhtmlじゃなくhtmってなって、WORDで開いて.docにも変換可能です

質問はhtmって一般常識として普及しているのかどうかです
みなさんは、仕様を書くソフト（拡張子）は何を使ってますか？

224 ：デフォルトの名無しさん：2005/06/12(日) 14:51:50

>>223
テキストで管理して変換変換
.txt→.htm→.pdf と

225 ：デフォルトの名無しさん：2005/06/12(日) 15:10:03

>224
なるほど、テキスト最強ですな。
でもページ上でリンクしたいから、テキスト厳しいかも。
変な表とか入れずに、互換性上げるのには気をつけてます。

226 ：デフォルトの名無しさん：2005/06/12(日) 15:29:56

>>223
htmlをWORDで作るってのが個人的には好きではないが。

htmlは電子文書としては最強の一つだと思ってるよ。PDFよかぜんぜん好き。
仕様書は紙で出してナンボと思ってる古い業界体質も残ってるから
ウケはあまりよくないかも知れないけどね。

227 ：デフォルトの名無しさん：2005/06/12(日) 18:54:41

cssにしろXSLにしろ、理念は良いのだけど
どうせならもっと徹底して、テキストを完全に分離して欲しかったなぁ

テキスト側はもう生txtそのままでさ、
スタイルシート側は、面倒でも行で指定する感じ

実際は簡単なツールで補えば、行指定やテキスト変更も、手間でも無いだろうし

228 ：デフォルトの名無しさん：2005/06/12(日) 19:41:15

>>227
行指定は面倒すぎだろ
あと、その概念はWord文書みたいだ

229 ：デフォルトの名無しさん：2005/06/12(日) 20:26:40

>>227
確かに両方用意しないと行けない場合に便利だな。
頭の固いおっさん向けに、紙に印刷する必要がある時とか。

230 ：デフォルトの名無しさん：2005/06/12(日) 23:17:56

>>229 頭の柔軟な若者にも紙に印刷する必要があるだろ？

231 ：デフォルトの名無しさん：2005/06/13(月) 01:14:18

>>223

自分ならdoxygenでRTFで出力してpdfに変換して添付ファイルにするか、
WORDでRTFを開いてDOCに保存しなおすか。

RTFだとリンクはそのまま残るし、ドキュメントとしてもそれなりに
綺麗に出力されるからお勧め。一度試してみれ。

232 ：デフォルトの名無しさん：2005/06/13(月) 01:22:28

みなさんいろいろ言ってますが
それでお客に納品するの？
おいらは、Visioやパワーポイントも使わないようにしてるけど
打ち合わせ資料で使うときあるけど、最終的にはエクセルで書き直す事になる

233 ：223：2005/06/13(月) 01:31:32

>>231
ふむ、試してみます

234 ：デフォルトの名無しさん：2005/06/13(月) 03:52:03

XMLにコードとドキュメントを共存できる
XMLに対応したコンパイラ

235 ：デフォルトの名無しさん：2005/06/13(月) 11:35:27

>>234
XMLってマジで言ってますか？

236 ：デフォルトの名無しさん：2005/06/13(月) 20:30:41

>>234
XSLT使えばどうにでもなる気がする

237 ：デフォルトの名無しさん：2005/06/14(火) 13:26:23

つーかかつて Knuth というシトが
「文芸的プログラミング」(literary programming)
つーのを提唱して WEB つーシステムを開発したよね
それやりゃいいんだろ

238 ：デフォルトの名無しさん：2005/06/14(火) 21:01:39

　　　　　　　　　　 ,,ｒ'"　　　　　　　　　｀ヽ,、
　　　　　　　　　　　,r"　　.,/i、　　　　　 .ﾍ,　｀ヽ、
　　　　　　　　　　､"　　 ./::::::i,　　 /ヽ　 l..:::i,　　. '、
　　　　　　　　　 /　　 .,/:::::::::::i　　/.,:::l　i::::::::i 、　ヽ
　　　　　　　　　/　.,、.,i:::::::::::::::i,　/:::::::::v,,:::::::::l, ,li 　 i
　　　　　　　　 │ /:l./::::i::::|l::::::V,:::::::/i:::::::ﾍ::::::V::l,　. |　　,.,..,,.,..､、
　　　　　　 | ./:::l:::::::l-i:|-!::::::::::::::/ 'l:::/--l::::::;;;;l ..ﾚ'"´
　　　　　　 l .i::::::::::::l-i-'｡.ヽ::::::::/ ´l/-｡､i:::::::::::! ..i 　　可　理
　　　　　　　　　'!l:::::::: ﾍl |::::::l` i:::::/ 　ｲ::::::| ,!/::::::. i　|　　能　論
　　　　　　　 i::::/i::::l,｀￣｀　Ｖ　　￣　　 i::::i::::./　　な　上
　　　　　　　 V　l::::l,　　　　　　　　　 J /::::i "i/　　　ん　は
　　　　　　　　　ﾞl:::＼　　＿＿　　 ./l:::/ 　　　　　で
　　　　　　　　　　　　'!/　ヽ._ ヽ　ﾉ　,／" iv 　　　　す
　　　　　　　　　　　　　　＿.|｀ヽ- -イ|＿＜　　　　　　　　ﾟ
　　　　　　　　　　　　,,､ノ;;;;;;;|||||　 |||||;;;;;;;ヽ.｀!

SmartDocみたいな使えないものになるのが落ち

239 ：デフォルトの名無しさん：2005/06/26(日) 01:01:12

今のプロジェクトのドキュメントは
基本設計書からすべてExcelだ（´･ω･`）
確かに図を書くのがラクだけど・・・

240 ：デフォルトの名無しさん：2005/06/26(日) 17:00:24

質のいいスケルトンがあれば
Wordでもなんでもいいと思う

241 ：デフォルトの名無しさん：2005/06/26(日) 17:48:03

>>240
おれ、ワードは線がずれたら直せないんだよ。

242 ：デフォルトの名無しさん：2005/06/26(日) 17:52:50

>>241
根性、根性、ど根性

ちなみにIMEだとど根性で一単語になってる

243 ：デフォルトの名無しさん：2005/06/27(月) 03:53:01

IME

244 ：デフォルトの名無しさん：2005/06/27(月) 12:39:17

MS-IMEもATOKも「IME」だからな

245 ：デフォルトの名無しさん：2005/06/28(火) 11:06:46

MS-IMEがポピュラーになるまでは
FEPって方が通りがよかった。
だからついMS-IMEの事をIMEといってしまうま。

246 ：デフォルトの名無しさん：2005/08/21(日) 20:15:27

そんなことないよ

247 ：デフォルトの名無しさん：2005/08/22(月) 09:31:21

結局、仕様書書くのにどんなアプリつかっている？

俺の場合
図や表、文をまぜこみの仕様書である程度見栄えも気にする場合は、
OpenOfficeOrg2.0Betaを使っている。
Wordは俺は受け付けることができなかったが、Oooはなんとか好きになれそう。

htmlでやっているって言う人は、テキストエディタでごりごり書いているのだろうか？
ま、それが一番書きやすいのだが、そろそろhtmlエディタで良いのが出てきてほしいなあ。

248 ：デフォルトの名無しさん：2005/08/22(月) 19:05:24

マクロ使えるエクセルに決まってんじゃん
Wordは俺のUIと合わなかった

249 ：デフォルトの名無しさん：2005/08/27(土) 15:18:42

Wordは、いらぬお世話をするオプション類を全部OFFにして使えば使える。
挙動不審な事が多いし良く落ちるがドキュメントやマニュアルを書くのにはやっぱ
エクセルよりワードだな。

250 ：デフォルトの名無しさん：2005/09/03(土) 13:55:02

一度、どこかマ板辺りで
プログラマのためのワード講座
みたいなスレを立ててみようか

使いにくいと文句をいっている人は
例えるなら秀丸でVC++のソース編集してるようなもので
きちんと環境構築と突然死への備えを整えれば
VisualStudioなみの便利さを手に入れることはできる

251 ：デフォルトの名無しさん：2005/09/10(土) 01:05:56

僕は、LaTeXちゃん！

252 ：デフォルトの名無しさん：2005/09/10(土) 04:56:03

うちは何故かエクセル。開発環境はLinux＋Eclipseなのに、文章作成は
Windowsでエクセル（ﾟдﾟ）ﾎﾟｶｰﾝ
社内通達がエクセルで回って来た事もある。本文無しで添付ファイル
があるだけという、思わずゴミ箱に放りそうになったぞ。

それはそれとして、前に文章作成なのに何故エクセル？という問いを
投げてみたんだが、エクセルで何の問題がある？と聞き返されて有耶
無耶になった。
ワードを使えば云々と言えるほど、俺はオフィスツール知らんからな。
て言うか、正直エクセルも線の引き方と文字の属性変更くらいしか知
らんのだけどねorz

誰もが納得するワードの利点とかあるなら聞きたい＞250

253 ：デフォルトの名無しさん：2005/09/10(土) 08:15:48

>>252
おぢさん達はExcelが大好きなのです。
日々の報告書からプレゼン資料まで、全部Excelで作ってくれます。
Wordは勝手に整形しやがるから使いにくいそうです。
罫線使いまくりの日本語文書はExcelの方が使いやすいんでしょう。

250じゃないが、誰もが納得するWordの利点：（取引先も含めて）みんなが使ってる

254 ：デフォルトの名無しさん：2005/09/10(土) 09:31:46

目次勝手につくってくれる

分厚い仕様書を方眼紙みたくしたエクセルで書かされて
目次の管理で死にました。

255 ：デフォルトの名無しさん：2005/09/10(土) 15:11:30

>>252
スタイル

なぜかあんまり使われていないようですが……

256 ：名無しさん＠そうだ選挙に行こう：2005/09/10(土) 19:01:51

>>252
エクセルだと表計算と図と文章作成、全てエクセル
でやろうと思えば済んでしまうらしいので、プレゼン資料
とかも全部エクセルだけにしてる奴がたまにいるｗ

257 ：名無しさん＠そうだ選挙に行こう：2005/09/10(土) 20:13:54

>>253
みんなが使ってる度ならExcelの方が上じゃない？
少なくともWordの方が一方的に有利って事はないと思う。

>>255
初めて聞いたｗ

>>256
最近、MindManager(MindMap)が大人気。
少し前はEA(UseCase)が大流行だったが
次は何が流行るんだろう？

258 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 00:56:45

>>257
Wordのスタイル、少し覚えてみなよ。
マジデ便利だから。

259 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 01:08:00

なんか興味が出てきてWordを立ち上げてみる
インストールして5年は経っているが、たぶんこれが起動2回目くらいだな

んでしばらくイジくってみたんだけど、テキストボックス使えればOKな感じでいいのかね？
他にめぼしい機能あるかな。些末なの抜きで。

260 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 03:38:57

>>259
>些末なの抜きで。

Wordの売りはむしろ些末な機能が豊富にあるとこかもしれんｗｗｗ

261 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 03:40:38

デフォ設定で自動補正になってなけりゃもっと評価高いかも
迷惑な便利機能を殺したくてその便利機能について学ぶという不毛な時間がすごくアレだ

262 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 04:01:28

でも、ホント、Word の売りってなんなんだろうな？

パワポは俺も最近までは全然評価してなかったんだけど、会議で使う資料をパワポで作ったら、
いつもテキストファイルで書いてる内容と変わらんのに、妙に内容の評価がよくてﾜﾗﾀ。
やっぱり人は体裁で騙されるもんだなｗｗｗ　　・・・それからはパワポに一目置いている俺ｶﾞｲﾙ。

263 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 11:27:31

>>262
発表において、体裁ってもんがどれほど重要か。
どんな小手先の技でもいいから、人の気を引くというのは大切よ。

Word の利点、ぱっと思いついたのだと、
- 修正履歴を残せる → 学生の論文チェックとかかなり楽
- コメントを付けれる → これも校正に凄く便利
- スペルチェック → 英文はとりあえず最初 Word で書いとけみたいな
- 一応、段落ごとにスタイル定義しておいて、スタイルの書式変更したら同じスタイル一斉に変更される

264 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 13:27:47

Wordで20ページ↑の仕様書を書いてみればわかるよ
スタイルとかクロスリファレンスつけておくとマジ便利
目次や索引も自動で作れるし。
これでもう少し図形描画の機能が充実してればなぁ・・・
ま、そっちはVisio使ってるからいいんだけど。

#でも、個人的にはLaTexを吐いてくれるエディタが欲しいところ

265 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 13:29:26

利点
- 目次作成 + 自動更新
- 図表番号の自動更新

266 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 17:20:24

>>263-265

どれも俺からすると些末な機能なんだけど。

XSLTが大好きな俺的にはXML形式に対応してるところなんかが蝶最高なんだけど、
これはExcelやパワポでもできることだしな。

267 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 17:33:54

Wordの最大のウリは
多数派であるということ

268 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 17:50:31

>>264
最近のはマシなんか？
Wordでページ数多い文書作ると重いわすぐ落ちるわで……
いい印象無かったんだが

269 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 18:28:11

>>264-265
この辺のテンプレート集とかスクリプト集ってある？
折角の利点も簡便で分かり易くないと説得が難しい。
偉いさんてのはプライドを刺激されると意固地になるからな。彼らは難しいとか
理解できないを決して口にせず、それらを必要がないの一言で片付けてしまう。

270 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 18:32:51

>>267
Excelの方が多数派だよ？
総務などの非生産部門には必ずと言っていいほどExcelが導入されてるから

271 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 18:33:14

>>269
目次だのなんだのって、単なるWordの基本機能だから、スクリプトは不要だよ。
ちゃんとスタイル使って（「見出し1」とか「見出し2」とか）文書を
書けば、章番号を自動で振ってくれるし、後でそれをもとに自動で目次が作れる。

272 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 18:34:18

>>270
ExcelとWordでは用途が違うというだけの話だ。
適材適所で使い分けるのが賢いやり方。

273 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 18:51:04

>>271
ありゃ？そうなのか、て言うか基本機能なのかよ！
俺自身が実際に触って、基本機能くらいは理解しないと話にもならんな＿|￣|○|||
それが何とも億劫と言えば億劫なんだが……
俺も偉いさんの事をとやかくは言えんな……

>>272
問題は、決して賢くないという点だ！Σ(´Д｀）

274 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 19:02:01

>>273
http://www.amazon.co.jp/exec/obidos/ASIN/4774117501/
この本がおすすめ。

アウトラインモードで取り敢えず書くのが
自然に思えてきたら結構使ってる人なんじゃないでしょか。

275 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 21:47:06

>>273
俺、元々LaTeX派だったけど、3日でWordに転向しちゃったよ。
割とすぐ覚えれる。

276 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 21:50:52

>>274

この本、自分も人から薦められて買ったけど、かなりいい本ですね。
職場に一冊常備すべし。

277 ：名無しさん＠そうだ選挙に行こう：2005/09/11(日) 22:54:18

Win板かソフ板の話題が続いている件について

278 ：デフォルトの名無しさん：2005/09/12(月) 00:35:07

>>274-276
ホントかよ？ジエリじゃねぇだろうなｗ
とりあえず明日本屋行ってくるよ。初心者向けではないみたいだから
一緒に入門書も買ってくる。

279 ：デフォルトの名無しさん：2005/09/12(月) 00:59:59

>>278
じえんじゃないよ。
まあじえんだとしてもいいじゃん
本屋で立ち読みしてみて決めてちょー。

カラーページがないところとかが硬派で
それだけで好感が持てますだ。

DTPのマナーみたいな話も、システム文書には
必要ないけど、面白かったな。

280 ：デフォルトの名無しさん：2005/09/16(金) 00:55:41

Wordのスタイル機能は書式をいぢりづらいのがネック。
特にスタイル使わずに書かれた文章にスタイルを導入しようとすると死ねる。

281 ：デフォルトの名無しさん：2005/09/16(金) 10:45:36

>>280
あとからは相当骨でしょそりゃー。

282 ：デフォルトの名無しさん：2005/09/23(金) 00:26:28

なんかMSワードって何処でも決まって悪者にされる傾向があるけどなんでだろうね。
俺はかなり良いソフトだと思うんだけど。いやマジで。

今までアドビのフレームメーカーとかロータスのワードプロも触ってきてるけど
ワードのUIはそれらより飛びぬけて直観的だし、機能も多い。

ワード使い難いって奴はフレームメーカー使ってみるといいかも。
フレームメーカーの糞UIはマジで殺したくなるよ。それでいてワードより高かったりしたから恐れ入る。

まあでも時々挙動不審だったりするし、段落番号の設定みたいに異常にわかり難い
UIがあったりする欠点は確かにあるな。

それにしても、ワード貶してる奴らに関しては、ワードの問題というより
そいつらの能力の問題じゃないかと思うが。

283 ：デフォルトの名無しさん：2005/09/23(金) 01:07:59

デフォルト設定のせい
UNIXが使いにくいのとおなじ

284 ：デフォルトの名無しさん：2005/09/23(金) 11:01:41

それにしても、UNIX貶してる奴らに関しては、UNIXの問題というより
そいつらの能力の問題じゃないかと思うが。

285 ：デフォルトの名無しさん：2005/09/23(金) 14:04:57

じゃあWordに文句を言うやつも無能だな。

286 ：デフォルトの名無しさん：2005/10/10(月) 16:31:55

>>285
そりゃ無能だろ

287 ：デフォルトの名無しさん：2005/10/10(月) 17:27:01

あーでもWordの使いにくさとUNIXの使いにくさは別だな。
UNIXはどうしようもないからな。

288 ：デフォルトの名無しさん：2005/10/10(月) 17:33:25

doxygen 1.4.5 age

289 ：デフォルトの名無しさん：2005/10/10(月) 17:34:07

なんで並列に語ってるのか知らないけどあえてノルなら
Wordの使いにくさは袋小路であり、UNIXの使いにくさは迷路だ。

Wordでやりたいことをやるとき、正式な方法が無いことはよくあり
正式じゃない方法で突破することが多い
UNIXでやりたいことをやるとき、正式な方法がそもそも難解で
そのことを訴えると「道があるんだからいいだろ」と突っぱねる

290 ：デフォルトの名無しさん：2005/10/10(月) 18:29:51

Linuxの場合、とっつきやすさや使いやすさを最初から目指していないのだから使いにくくて当然な気がする。
Wordはなー。MSってUIにけっこう力入れてるはずなのになんであんなことになるのか。

291 ：デフォルトの名無しさん：2005/10/10(月) 19:38:35

英文だと一般の評判多少マシなのか？

292 ：デフォルトの名無しさん：2005/10/11(火) 11:07:21

ドキュメンテーションを書くときは常に例を書き込むとかなりグー。
PHPのドキュメンテーションなんていい例じゃないかな。
使い方系のドキュメンテーションはシナリオ書いとく。

ところで、結局Wiki立てても書くのは結局一人だけだよなぁ。
でもみんなで書くという機能よりも手軽にどこからでも書けるというのが気に入ってる。
使いこなすとかなり快適。あとはVISIOでちょっと図を描いて終了。

293 ：デフォルトの名無しさん：2005/10/27(木) 03:40:16

確かにリファレンスとかは、
動作例ある方が読みやすいもんな。

つーか動作例無いと、リファレンスに見えないというか。

294 ：デフォルトの名無しさん：2005/11/01(火) 01:47:40

ドキュメントなんか書いてる暇があったらソースを書け。

295 ：デフォルトの名無しさん：2005/11/06(日) 15:48:48

概要仕様はワープロソフトできっちり作るな。納品しやすいし。
細かい仕様はソースにコメント埋めまくり。

ワードとかUNIX使いこなせない香具師はスキル低いだけ。

何か一つだけしか覚えられない香具師がエクセル使っている感が有るな。
自由紙、原稿用紙、レポート用紙、方眼用紙っていろいろあるけど、どれか一つ選べって状態で方眼紙選んじゃってるだけだ。
レポート用紙にグラフも書けるのにさ。

296 ：デフォルトの名無しさん：2005/11/11(金) 16:36:53

どのソフトを使うかなんか関係ないって。中身ですよ中身。
つーか、こんだけソフト開発が行われてるんだから、もちっとドキュメント作成技術も洗練されていてくると思うんだけどな～。
どこのプロジェクト行っても、読まれない＆読んでも意味ないドキュメントばっか。
新規で起こす時も役にたたねぇだろうなーと思いつつ作ってるし。

それともオレが知らないだけで、既に良いツールor作成理論とかあったりするの？
もしあったら教えてエロイひと

297 ：デフォルトの名無しさん：2005/11/11(金) 22:53:22

>>296
コツを教えてあげるよ

自分が欲しいと思えるドキュメントを作ればいいよ
役に立つように作るべし
役に立たないと思った個所はどんどん削除

298 ：デフォルトの名無しさん：2005/11/11(金) 22:55:25

あと、起承転結では読みづらいので起結承転を心がけること

299 ：デフォルトの名無しさん：2005/11/11(金) 23:11:01

正直「転」はいらん。

300 ：デフォルトの名無しさん：2005/11/11(金) 23:23:41

統合設計書作成アプリケーション作って。
普通のアプリでWikiっぽい機能＋Wordの章番管理＋Excelみたいな表が
自由に作れる幹事で

301 ：デフォルトの名無しさん：2005/11/12(土) 08:19:16

転ってアレか。

この関数は○○の機能を持つ <- 起結
ただし、××の副作用を持つ <- 承転

302 ：デフォルトの名無しさん：2005/11/12(土) 17:11:51

さすがにtxtを推奨する奴はいないようだ。

303 ：296：2005/11/14(月) 09:43:53

いや、ドキュメント書けないわけじゃないないけどね。
この業界、結局ウォーターフォール型がほとんどじゃない？
だったら　要求＞仕様＞設計＞試験　ぐらいのテンプレートとか支援ツールあってもいいんじゃねーかなと思って。
それに有名な規格ができたら、顧客の理解度、満足度ももっと高くならないかなぁ。とか
（Rational Rose とかは勘弁な。”UML図”だけじゃレビュー通らないし）

あと変に思うのは設計書。実装イメージをそのまま文書にしたのをよく見かけるけど、設計書は利用者ガイドであるべきだと思うんだ。
あの高いソフト買うと付いてくる大量のマニュアル郡みたいに、コンセプト、概要、実装サンプル、注意点、とか。
設計者が変わりに文書で実装しても意味ないっしょ。

あ～ぐだぐだと駄文書いてスマヌ

304 ：デフォルトの名無しさん：2005/11/14(月) 10:41:15

俺もそう思う。
納品物としての仕様書なんかいらん。読んでくれないし。
きっちり書いたユーザーマニュアル納品すれば一番ブレがない。
要求は全てそこに落とせばいいんじゃないかなあと。
だからマニュアルといっても画面の説明だけじゃなくて
半分業務マニュアルって感じ。

所謂仕様書らしい仕様書は、
お客さんにガッチガチの情シスがあって
そこが出せっていうんだったら書くよ、って感じで
いいんじゃないでしょうか。

なんか仕様書とあまり変わらないか。
でも言葉とかフォーマットとか、もっとお客さんに優しい感じ。

305 ：デフォルトの名無しさん：2005/11/14(月) 13:50:36

納品物としての仕様書は、
質重視ではなく量重視だな。

306 ：デフォルトの名無しさん：2005/11/14(月) 15:40:39

すると普通の仕様書より表現が冗長になりそうな
マニュアルでの納品がやっぱいいな
スクリーンショットわんさかで

307 ：デフォルトの名無しさん：2005/11/14(月) 21:10:06

>>301
そんな感じ
注意事項

308 ：デフォルトの名無しさん：2005/11/15(火) 01:24:59

>>306
マニュアル + クラス仕様書(自動生成したもの) が最強。
そして両面印刷なんてもってのほか。

309 ：デフォルトの名無しさん：2005/11/29(火) 03:00:58

>>254
亀レスすまそ。

よくExcelのセルを方眼紙みたい（正方形）にする人がいるんだけど、
あれって何が便利であんなセルにしちゃうわけ？
レイアウトしやすいってだけ？

310 ：デフォルトの名無しさん：2005/11/29(火) 10:04:30

本当に方眼紙に仕様書を書いてた名残らしい。
あと、インデントしやすいからといってた。

311 ：309：2005/11/30(水) 18:12:53

>>310
方眼紙ってそのまんまかいなｗ

312 ：デフォルトの名無しさん：2005/12/31(土) 19:33:11

doxygen 1.4.6 age

313 ：デフォルトの名無しさん：2005/12/31(土) 20:00:13

wiki風の装飾付きtxtを書いて、自前ツール通してhtmlにしてるな。
リンクやレイアウトが簡単だし、ブラウザは誰でも入ってるから。

314 ：デフォルトの名無しさん：2006/01/25(水) 17:59:27

doxygenのマニュアル読んでも、「使わねー」とか「ソース汚なくなるだけー」
みたいなコマンド(キーワードや記法)が多いと思ったんだけど、どう？
おまいらのdoxygenボキャブラリーはどんなもんよ？

315 ：デフォルトの名無しさん：2006/01/25(水) 22:45:51

file brief author
pre post param return retval
後メンバグループにname { }

316 ：デフォルトの名無しさん：2006/01/27(金) 09:26:58

>>315
それだけあれば、ひととおりの仕様は説明できそうだよね。
「意見」なんかを入れはじめるとややこしくなるんだよね。

317 ：デフォルトの名無しさん：2006/02/25(土) 02:38:32

ドキュメントが書けないやつは自分の頭でわかってないからだ。
自分ではわかってるけど説明するのが下手というやつは、自分でも
わかってない。それは直感と連想能力とヒントでピントでプログラミング
してるだけだ。

318 ：デフォルトの名無しさん：2006/02/25(土) 11:59:02

16分割の最初の2枚ぐらいでわかっちゃうようなやつには
ドキュメント作成なんてまだるっこしくってやってられんのだろうな。
馬鹿の気持ちが分からないから、標準からはずれたのを作成してしまう。

医者なんかでもそうだけど、臨床とかエンドユーザーが絡む作業は
あんまり頭が切れるヤツは向いてなくて、
ちょっと馬鹿だけどそれを自覚して慎重・着実に作業する
ヤツの方が向いてる。

319 ：デフォルトの名無しさん：2006/03/04(土) 02:25:09

ソフトウェア開発の世界標準フォーマットみたいなもの無いかな
各工程で何の文書が必要で、どのような項目を記載するものだ、みたいな

320 ：デフォルトの名無しさん：2006/03/32(土) 17:58:17

UMLって客に見せても実際は理解してもらえない。
客側に上級シスアドみたいなのがいれば話は別だが、現在ではそんな状況はあまりない。
結局UMLで書くってのは設計者のオナニーなんだなと思う。
なにしろUML試験なんかあるくらいだから、コンピュータど素人のお客にわかりやすいわけがない。

ところでXP開発におけるドキュメントの生成の仕方ってどうしてる？
うちは要件定義書が文章じゃなくて業務フローのの図だけなんだが。
そんなのが入力では詳細設計書なんて書けないぜ。

321 ：デフォルトの名無しさん：2006/03/32(土) 18:31:53

UMLは客に理解してもらうためのもの、
なんて言ってる人はあなた以外に見たことありませんけどw

自分が勝手に銀の弾丸を求めてるだけでしょ？
銀の弾丸がきっとあるに違いないと無意識に思ってるから
ネジ廻しがネジを締めることにしか使えないことに苛立つんだよ。

322 ：デフォルトの名無しさん：2006/03/32(土) 18:57:02

＞UMLは客に理解してもらうためのもの、
＞なんて言ってる人はあなた以外に見たことありませんけどw

見聞が狭いんだね。俺は何人か知ってるよ。
見たこともない、とは重傷だな。

323 ：デフォルトの名無しさん：2006/03/32(土) 20:35:16

ダメなドキュメントってあるよね。当たり前のことしか書いてなくて、
ポイントが抑えられてないような。
UMLだろうがワードだろうが、同じ人間が書く限りダメなドキュメントなのは変わらないのが現実

324 ：デフォルトの名無しさん：2006/03/32(土) 23:02:48

ドキュンメント

325 ：デフォルトの名無しさん：2006/04/09(日) 00:06:13

みんなはdoxygenでコメント書くとき
Qtスタイルにしてます？JavaDocスタイルにしてます？

326 ：デフォルトの名無しさん：2006/04/09(日) 17:17:32

JavaDoc スタイル。
Qt ってマイナーだし Qt にするメリットってあるの？

327 ：デフォルトの名無しさん：2006/04/09(日) 20:37:45

>>320
むつかしく書きすぎ、細かく書きすぎ
なんじゃないの？

328 ：デフォルトの名無しさん：2006/04/09(日) 21:42:04

言われてみればそうだよな…・。
伝えるだけなら、
紙に手書きしてコピったりスキャナで取り込むなりの方が遥かに敏速。

329 ：デフォルトの名無しさん：2006/04/10(月) 03:00:04

>>319
それこそ本屋にいけば山ほどその手の本があるやん。
成果物が一番はっきり明示されているのはラショナル統一プロセス
じゃないの。ISO9001なんかを取得している会社なら社内標準で
成果物が設定されているでしょ。

>>320
オブジェクト指向言語で開発しているなら、それとの親和性の
高さという点から、内部設計はUMLでするのはいい。けど、
要求仕様をユースケースなんかで顧客に見せるやつの気が知れない。
というかそういうやついるのか？俺はずっと前からアンチユース
ケース派でそういうことばっかり言っているけど。

330 ：329：2006/04/10(月) 03:02:49

>>319
それと追記するけど、どんな職場や環境、メンバーのスキルに
合致した魔法の世界標準フォーマットは存在するわけがない。

それぞれに合致したものはそれぞれが苦労して考えるしかない。
参考にするのはいいけど、巷に出回っている開発プロセスを
そのままやろうとすると失敗するよ。

331 ：デフォルトの名無しさん：2006/04/18(火) 15:12:14

質問。

仕様書だけ書いて、それを
ベクターみたいに、アップロードして
みんなに見せるサイトって、どこかある？

332 ：デフォルトの名無しさん：2006/04/18(火) 15:15:33

参考。仕様書相互リンク

良いドキュメント・マニュアル・仕様書を書くスレ
http://pc8.2ch.net/test/read.cgi/tech/1065364445/

小規模開発では仕様書は作るだけ無駄
http://pc8.2ch.net/test/read.cgi/prog/1125913671/

AJAX時代の仕様書とは
http://pc8.2ch.net/test/read.cgi/tech/1140766471/

営業が作った仕様書に
http://pc8.2ch.net/test/read.cgi/prog/1121256149/

良い仕様書、悪い仕様書、普通の仕様書
http://pc8.2ch.net/test/read.cgi/prog/1143906019/

プログラマ経験がないのに仕様書を作成
http://pc8.2ch.net/test/read.cgi/prog/1119776686/

仕様書の量でしか成果を決められない客
http://pc8.2ch.net/test/read.cgi/prog/1143878620/

Excelで仕様書を作る会社の奴の数→
http://pc8.2ch.net/test/read.cgi/prog/1137662854/

333 ：デフォルトの名無しさん：2006/04/19(水) 02:18:12

Doxygenの質問はここでいいのかな…？

HIDE_UNDOC系のタグをYESにしててドキュメント付けした要素だけ
書き出してるんだけど（もちろんEXTRACT_ALLはNO）
\fnとか一行コメントとか付けてない関数を強制的にドキュメントに含めてよ！
って指示するコマンドありますか？

今は全角空白の一行コメント付けて無理やり出してるんだけど
リスト表示のとこで無駄に下に空白ができちゃってみづらいんです
（同じページに列挙したいけどわざわざコメント付けしたくない関数ってのがいっぱいある）

334 ：sage：2006/04/28(金) 11:10:03

コーディングは製造であって、
その前に設計仕様書があるべきだと思うんですが、
DoxygenやJavaDocで出したものを、仕様書にするってことは
それ以前にモジュール設計仕様書とか無いままコーディング
してるんでしょうか？

335 ：デフォルトの名無しさん：2006/04/28(金) 12:19:21

中身ダミーで関数名と Doxygen 形式の仕様コメントだけ入れた骨組みをもって設計仕様ではダメなの？

336 ：デフォルトの名無しさん：2006/04/28(金) 13:07:44

で、実際んな事やってんの?って話だろ

337 ：sage：2006/04/28(金) 13:21:18

>>336
そりゃ、設計代もらってるんだからやりますよ
フリーソフトウェアの開発者とかなら話は別ですが…

338 ：デフォルトの名無しさん：2006/04/28(金) 13:55:57 BE:162918959-

鉄面皮で四角四面のウォーターフォール　うぜぇ

339 ：デフォルトの名無しさん：2006/04/28(金) 17:09:48

>>334
>コーディングは製造であって、

違います。
- コーディングは設計作業です
- ソースコードは設計成果物です
- コンパイル・リンクなどが製造工程になります

340 ：デフォルトの名無しさん：2006/04/28(金) 17:25:01

不正確でつまんない比喩なんてどうでもいいよ。

341 ：デフォルトの名無しさん：2006/04/28(金) 21:56:05

>>339
幸せだなぁ…
そう思ってるうちはコーダーから卒業できんよ

342 ：デフォルトの名無しさん：2006/04/28(金) 22:45:00

東芝とか日立とかの大手が集まって仕様書の標準作るらしいね。
２００７年をめどに完成予定とか。
どうなるのかな？

343 ：デフォルトの名無しさん：2006/04/29(土) 04:30:26

実行されたプログラムの動作こそが製造だ。
コーディングは、ラインの設計だ。

344 ：デフォルトの名無しさん：2006/04/29(土) 10:24:49

不正確でつまんない比喩なんてどうでもいいよ。

345 ：デフォルトの名無しさん：2006/04/29(土) 21:31:40

コードコンプリートの
メタファの章はよくまとまってるよ

346 ：デフォルトの名無しさん：2006/05/01(月) 20:45:13

Doxygenを実際使ってるプロジェクトってある？
俺は個人的にちまちまいじってるぐらいです。

みんなに使ってもらうにはやはり雛形を作成するしかないけど
どんなのがいいのか思案中。

なにかサンプルと成るものってあります？

347 ：デフォルトの名無しさん：2006/05/01(月) 20:49:42

>>346
Doxygen 自体
libstdc++
Subversion

いっぱいあるよ。
っていうか、雛形なんか要らないと思うけど。

348 ：デフォルトの名無しさん：2006/05/01(月) 20:54:11

Doxygenで悩むのがテンプレート定義しかないヘッダファイルへのコメント
そりゃヘッダに実装も書いてあるんだからそこにコメント付けるのが自然かもしれんが
各テンプレートの間にミッチりコメントが詰まってソースコードとして読みづらくなる（困

こういうときってコメントだけの空cppファイルとか作るんですかね？

349 ：デフォルトの名無しさん：2006/05/01(月) 20:58:42

>>348
Doxygen とか関係なしに、コメント書きすぎなんじゃね？
もしくはコメント書かざるをえない設計とか？

350 ：デフォルトの名無しさん：2006/05/01(月) 22:23:54

>>349
書きすぎってのはあるかも試練…
対象ユーザーのC++理解度が低い前提で書いてるんで
どう使ったらいいかのコード例みたいのもコメントに含んでるんだけど
やりすぎかね

@defgroup してモジュールの説明とか書き始めるともうコメントだらけですよ

351 ：デフォルトの名無しさん：2006/05/02(火) 16:26:03

サンプルみたいなものが書いてあるならそれはコメントとは呼ばないよ

352 ：デフォルトの名無しさん：2006/05/05(金) 14:12:41

doxygenだと__declspec(property)とかがメソッドとして認識されちまう。
なんかうまい方法ある？
っつーかこんなん使うなって話になりそうな気もするけど

353 ：デフォルトの名無しさん：2006/05/06(土) 13:39:38

>>352
プリプロセッサで消せば？
こんな感じで。
#ifndef __MSC_VER
　#define __declspec(arg) /* ignore */
#endif

354 ：デフォルトの名無しさん：2006/05/11(木) 01:18:44

おぉ？
http://www.doxygen.jp/

355 ：デフォルトの名無しさん：2006/06/11(日) 22:16:55

Doxygen 1.4.7 age

356 ：デフォルトの名無しさん：2006/06/14(水) 14:33:53

ちょっと見やすくなったね＞1.4.7

357 ：デフォルトの名無しさん：2006/06/22(木) 09:09:28

1.4.7 で dot を使おうとすると FreeSans.ttf が見つからんエラーになるなorz
まあ、すでに bugzilla に報告済みだから次のバージョンでは何らかの対策がされることを
期待するが。

358 ：デフォルトの名無しさん：2006/06/22(木) 10:13:30

【佐賀】サムスンSDS開発のシステム不具合で市が課税ミス　昨年度はSEがデータだけ修正して誤魔化した？
http://news19.2ch.net/test/read.cgi/newsplus/1150936122/l50

佐賀市は１９日、市税や住民票などを管理する市独自の基幹システムでプログラムエラーが
あり、国民健康保険税に課税ミスがあったと発表した。

この基幹システムは、旧市が韓国ＩＴ大手の「サムスンＳＤＳ」と約８億７千万円で共同開発し、
０５年４月から運用を始めた。開始直後は約５０人の同社員がエラーをチェックしていた。

市情報政策課は「昨年度もエラーはあったはずだが、データを手直ししただけで、プログラム
自体を修正しなかった可能性が高い」と話している。

359 ：デフォルトの名無しさん：2006/06/29(木) 23:09:03

http://www.atmarkit.co.jp/fwin2k/itpropower/admin-kun/031/adminkun031.html

360 ：デフォルトの名無しさん：2006/07/16(日) 19:06:32

doxygenで

/// @file test.hpp
/// @brief doxygenテスト

/// 加算
int add(int a, int b);

/// 加算
加算double add(double a, double b);

をドキュメント化すると最初のint add(int a, int b)しか載りません。
クラスのメンバ関数はオーバーロードしたものもドキュメントに載るのに。
何か方法はないでしょうか？

361 ：デフォルトの名無しさん：2006/07/16(日) 19:15:50

>>360
その加算double ってのは何だ？

362 ：デフォルトの名無しさん：2006/07/16(日) 19:23:54

タイプミスです。すみません。

/// @file test.hpp
/// @brief doxygenテスト

/// 加算
int add(int a, int b);

/// 加算
double add(double a, double b);

363 ：デフォルトの名無しさん：2006/07/24(月) 11:03:53

.bat, .vbs, .rb等々どんなソースにも仕込める
簡単な書式のヘルプ作成ツールみたいなのないですか？

例えば.batなら

@echo off && goto enddoc
<title>mytool</title>
<description>なんか役に立つツール</description>
<parameters>
-h: このヘルプを表示
-v: verbose
</parameters>
:enddoc
...
メインの処理

とかやっといてフィルタかますとmytool.htmが生成されるとかそんな感じのもの

364 ：デフォルトの名無しさん：2006/07/24(月) 18:39:30

>>363
その程度だったら、
自分でRubyかPerlあたりでフィルタ作ればいいんじゃない？

上の例を借りると、

@echo off && goto enddoc
REM @XX_BRIEF <title>mytool</title>
REM @XX_BRIEF <description>なんか役に立つツール</description>
REM @XX_BRIEF <parameters>
REM @XX_BRIEF -h: このヘルプを表示
REM @XX_BRIEF -v: verbose
REM @XX_BRIEF </parameters>
:enddoc

とでもしておいて、
行中に@XX_BRIEF等の特定のキーワードが含まれるかチェック
→ キーワードの後ろから行末までの文字列を抽出
→ 必要に応じて文字列を整形し、特定のフォーマットに変換
→ ファイルに出力

という感じで。
ソースコード内の変数名やメソッド名を参照するようなことはできないけどね。

365 ：デフォルトの名無しさん：2006/07/26(水) 04:08:38

>>360, 362
1.4.7 で問題なく出力できた。

366 ：デフォルトの名無しさん：2006/07/28(金) 01:57:06

DQNメント

367 ：デフォルトの名無しさん：2006/10/18(水) 11:22:21

Doxygen 1.5.0 age

368 ：デフォルトの名無しさん：2006/10/30(月) 01:23:57

doxygen 使ってますが、
> Generating caller graph for function foo
という行で止まってしまいます。

いつも同じ関数の処理をしている時に止まるようです。
止まってしまう関数の処理を中断して先に進ませる方法はないでしょうか？

369 ：デフォルトの名無しさん：2006/10/30(月) 11:19:27

Doxygen 1.5.1 age

370 ：デフォルトの名無しさん：2006/10/31(火) 00:35:52

doxygenだと改行が無視されて
せっかく綺麗に作ったコメントがぐちゃぐちゃになるんだけど
なにか対策ある？

371 ：デフォルトの名無しさん：2006/10/31(火) 00:43:23

>>370
<pre></pre> でどう？
場合によっては何かもっと適切な対策があるかもしれないけど。

372 ：デフォルトの名無しさん：2006/11/01(水) 00:55:01

\n書くとか。
漏れはもう改行を気にするのはやめたけど。

373 ：デフォルトの名無しさん：2006/11/01(水) 13:48:26

>>370
doxygenの整形に任せるのが正解。
改行が必要なほど複雑な説明を長々とコメントに書いてはいけない。
補足説明とか引数別の説明とか例外のリストとかそういうのは
それようのタグがあるのでそれを使ってdoxygenに整形させる。

374 ：デフォルトの名無しさん：2006/11/11(土) 11:36:25

楽にドキュメントを書ける(・∀・)ｲｲ！ツールすらないことがよくわかった。
おまいら今なら作れば売れるぞw

375 ：デフォルトの名無しさん：2006/11/11(土) 12:00:06

脳味噌にUSBケーブル接続して脳内仕様をダイレクトに出力できるデバイスが
発明されない限り、ドキュメント作成ツールのメガヒットはありえない。

376 ：デフォルトの名無しさん：2006/11/11(土) 13:26:33

えーそんなの出来たら
おっぱいとか満載になっちゃって大変そう。
雑念払う練習しないと。

377 ：デフォルトの名無しさん：2007/01/08(月) 23:42:18

ソースがドキュメントとか逝ってる人、勘弁してよ。
ちょっと不思議な動きしてるんですけど、
ソースのバグなんだか、仕様なんだか、わからないよ！

と、１０年以上前に誰かが作ったソースをメンテさせられることになって
鬱状態の僕は思いました。５万行もあるよ。。

みんな、doxygen使ってるか！
ちゃんと、その関数が何やりたいのとかきちんと書いてな！
あとsunのJavadocみたいに、スレッドセーフかどうかとかも書いてあるとうれしいよ！

パッケージとかモジュールとか、ソースより大きい単位でも
doxygenってドキュメント書けるの？

>>374
買うから作って。

あけましておめでとう。

378 ：デフォルトの名無しさん：2007/03/10(土) 16:46:51

"要求定義"
"要件定義"

同じものを違う呼び方してるだけ？

379 ：デフォルトの名無しさん：2007/03/10(土) 17:25:20

>>378
レイヤーが違う
上位が要件、下位が要求

380 ：デフォルトの名無しさん：2007/03/10(土) 17:53:37

なるほど。
これらを区別していない書籍も多いと思ったのですが、
そんなことないでしょうか？

381 ：デフォルトの名無しさん：2007/03/10(土) 17:55:28

多いか少ないかなんて問題なのか？

382 ：デフォルトの名無しさん：2007/03/10(土) 18:40:21

学習者にとっては問題です。

それぞれ英語では何という語句にあたりますか？

383 ：デフォルトの名無しさん：2007/03/10(土) 20:30:09

>>382
要件はマターとかファクター
要求はリクエスト

384 ：デフォルトの名無しさん：2007/03/10(土) 20:52:38

requirement...

385 ：デフォルトの名無しさん：2007/03/10(土) 21:02:38

>>384
requestもrequireも語源は同じですよ

re(再び) ＋ quaerere(ラテン語で求める)
再び求める ⇒ 要求、お願い

requireよりrequestの方が若干丁寧です

386 ：デフォルトの名無しさん：2007/03/10(土) 21:49:15

>>378
海外では"requirements definition"。
日本の計算機屋の言語感覚が鈍かったから、「要求」と「要件」がごっちゃになってる。
「要求」の方だけ覚えときな。

387 ：デフォルトの名無しさん：2007/03/10(土) 23:01:13

"要求"・・大学・研究機関で使われる
"要件"・・企業で使われる

だろ？

388 ：デフォルトの名無しさん：2007/03/10(土) 23:27:23

"要件"・・営業が使う

389 ：デフォルトの名無しさん：2007/03/12(月) 01:50:03

うーん。　難しいんですね。

レイヤーが違うというなら、
比喩的に、ボールペンの
要求定義、要件定義はどのようになるんでしょうか。

390 ：デフォルトの名無しさん：2007/03/12(月) 21:24:59

>>389

[要求]
先端は鋼などの硬球
運筆に応じて回転、軸内のインクが滲出

391 ：デフォルトの名無しさん：2007/03/12(月) 22:01:44

それは仕様じゃないの

392 ：こんなもんかな：2007/03/13(火) 10:29:20

仕様
速記に適し、それなりの耐久性を有すること。
ある程度の耐候性があればインクの種類は問わないが、掠れ難いこと。

393 ：デフォルトの名無しさん：2007/03/13(火) 10:52:47

[要求]
字が書けること

394 ：デフォルトの名無しさん：2007/03/13(火) 23:51:25

>>392
そっちのが要求じゃないの

あっこれマジレスってやつかっ？

395 ：デフォルトの名無しさん：2007/03/14(水) 00:16:56

「要件」は何？

396 ：デフォルトの名無しさん：2007/03/14(水) 00:48:48

要件定義書 ver0.00

- 普通紙に字が書けること
- インクの補充が容易であること
- 出来うる限りメンテナンスフリーであること

以上の要求を実現する筆記用具を開発することにより、ユーザーの利便性を高め
生産性の向上に（以下省略

＞以上の要求を実現する筆記用具を開発することにより、ユーザーの利便性を高め
＞生産性の向上に（以下省略
↑この辺が要件。

397 ：デフォルトの名無しさん：2007/03/14(水) 01:06:54

ttp://www.atmarkit.co.jp/farc/rensai/lookingfor04/lookingfor04a.html

少なくとも日本IBMでは区別してるようだな。
IEEEでは単にSoftware/System Requirements Speciticationであって、
区別してないようだな。

398 ：デフォルトの名無しさん：2007/03/14(水) 01:19:00

俺もIだけど、要求しか使わないよ。
上の例で挙げられているような仕様書は、
今どきコボラーくらいしか書かないんじゃないかな。

399 ：デフォルトの名無しさん：2007/03/14(水) 04:30:05

要望と要求と要件は微妙に違うという意見もある

要望は客が単に思ってること
要求はシステム上不可欠なこと
要件は実装するシステム機能

ま、いちいち分類したところで、結局ドキュメントを書かないもれには関係ない話だｗ

400 ：デフォルトの名無しさん：2007/03/15(木) 00:34:54

要件とは顧客の要望や要求を日本語に文章化したものではないかと思います。。。

その意味じゃ>>396の言ってる事がしっくりくるｗ

401 ：デフォルトの名無しさん：2007/03/15(木) 17:05:37

management textでいうプロジェクトリーダーの理解＝要件
ってこと？

402 ：デフォルトの名無しさん：2007/03/18(日) 15:15:13

プログラム単体レベルで考えると、破綻する。
システム全体を見据え、ドキュメントを体系化すべし。
富士通だと、SDAS
ttp://img.jp.fujitsu.com/downloads/jp/jmag/vol57-1/paper01.pdf

NEC、日立も似たようなもん持ってる。（どれが良いとかはシラン）
孫会社、下請けは知らないかもしれないが、本尊の動きくらい知っときなょ。

403 ：デフォルトの名無しさん：2007/03/18(日) 21:26:20

俺の考えは、

マニュアル　→　専門のテクニカルライターを使う
設計書　　　→　システム全体が見渡せるもの／外部仕様はしっかり書く。
　　　　　　　　内部仕様はほどほど。（結局ソースが正になるから）

ドキュメントが無いソフトは糞とかいうけど、
ドキュメントが無いと保守できないソフトこそ糞だと思う今日この頃だよ。

404 ：デフォルトの名無しさん：2007/03/18(日) 23:12:23

全体の概要とか外部仕様、内部仕様を区別せず、
一口にドキュメントの是非を問うから議論が分かれる気が。

>>403 が言うとおり、
システム全体像・外部仕様はしっかり、
内部仕様はソースが正、doxygen とかで自動生成
って言えば、あんまり反対する人いないと思うんだけど。

405 ：デフォルトの名無しさん：2007/03/18(日) 23:15:45

マーケティング部門向けの仕様書って
開発用と別に書いて渡してますか？

406 ：デフォルトの名無しさん：2007/03/19(月) 00:49:55

>>404
内部仕様書でも、分業単位の分まではきっしり作っておこう

407 ：デフォルトの名無しさん：2007/03/19(月) 04:40:13

>>403
上場企業だと、内部統制の関係で全てキッチリ必要

408 ：デフォルトの名無しさん：2007/03/27(火) 23:59:41

unmanagedとmanagedのコードが混在したアセンブリのドキュメントってdoxygenで出力できますか？
CVSに入ってるdoxygenだとCPP_CLI_SUPPORTという設定が使えるみたいなんだけど

409 ：デフォルトの名無しさん：2007/03/28(水) 09:19:09

>>407
上場企業というより、メーカー系の企業だな。
やつらは工場で作るものとソフトウェアを同じ体系にまとめようとするからムリがある。
上場企業でもソフトハウス系はそんなことない。

410 ：デフォルトの名無しさん：2007/03/28(水) 12:50:41

>>409
でも、工場で作るものと同じ仕様で仕様書を作っておくと
何年後でも開発者が死んだあとでもメンテが出来たりするので
あなどれないんだよな

411 ：デフォルトの名無しさん：2007/03/28(水) 18:55:58

小さな会社が手がけるレベルの開発じゃそこまでライフサイクル長くない…

412 ：デフォルトの名無しさん：2007/03/29(木) 09:16:07

あって役にたつのは、外部仕様書と内部実装の理解を助けるための簡単なドキュメントだな。
それ以上細かい内部仕様書は糞。
思うに、本当の内部仕様書ってのはソースコード自身だと思う。

413 ：デフォルトの名無しさん：2007/03/29(木) 11:35:18

>>412
それじゃバグがあっても仕様通りぢゃあないか

414 ：デフォルトの名無しさん：2007/03/29(木) 11:50:55

そうそう、大抵納品後数年経ってから発覚するような(必ずしもバグでない)不具合があったときに
一番役立つのがソースコードとソース内にきちんと書かれたコメントなんだよね。
尤も、それらがきちんと書かれていないコードに限って後から不具合が露見するんだが。
で、ついでに言えばそういうプロジェクトは大抵仕様書に仕様変更がきちんと反映されていないから仕様書は手掛かりにしからない罠。

415 ：デフォルトの名無しさん：2007/03/29(木) 12:14:21

勝手に転載

979 名前：デフォルトの名無しさん [sage] 投稿日： 2007/03/29(木) 10:14:13
処理Aの仕様書
・・・Aを実行する。

１行きたー。どうしよう。

416 ：デフォルトの名無しさん：2007/03/29(木) 23:41:27

良いDQNなんていません

417 ：デフォルトの名無しさん：2007/04/05(木) 13:28:09

Doxygen 1.5.2 age

UTF-8 ｷﾀ

418 ：デフォルトの名無しさん：2007/04/14(土) 22:07:50

要件定義書とか設計書とかのフォーマットはダウンロードできるとこありますか？
書籍でも良いです

419 ：デフォルトの名無しさん：2007/04/14(土) 22:33:19

RFP本とUML設計本くらいしか知らない。

実務資料はふつープロジェクト外秘や社外秘だから
必要なら会社で見せてもらえ

420 ：デフォルトの名無しさん：2007/04/14(土) 22:35:59

ためしに設計書フォーマットでググったら、
見覚えあるプロジェクトの公開資料が出てきてびっくらこいたｗ

421 ：デフォルトの名無しさん：2007/05/16(水) 01:23:38

スレ違いかもしれませんがdoxygen使いの方が
多そうでしたので質問させてください。

WinXPProSP1 VB6.0で開発を行っており、
このVBのソースをdoxygenに出力させたいのですが、
どなたか方法をご存知の方はいらっしゃらないでしょうか?

ネットを漁りvbfilterを使用し、tee.exe/gawk.exe/sh.exeも必要との事でインストールし、
input-filterに「C:\vbfiltervbfilter.bat C:vbfilter\tools」と入力し
なんとか変数一覧やメソッド一覧等が出力されるようになったのですが、
コメント部分の文字が化けてしまいます。

VBのソースがshift-jisで書かれておりdoxygenのinput-encodingが
UTF-8になっておりましたので、nfk.exeもインストールしdoxygenのinput-filterに
「C:\vbfiltervbfilter.bat C:vbfilter\tools|"nfk -w"」
としてみたのですがうまく変換されません。
(nfk単体で確認した所うまくshift-jis→utf-8変換処理は動作しておりました。)
恐らくdoxygenのinput-filter辺りでうまくパイプ処理が使えていないのが
原因だと思います。
４～５時間ほど試してみたのですが自分の力では解決できず
書き込みに至った次第です。

説明不足も多々有ると思いますがどなたか
方法をご存知の方がいらっしゃいましたらご教授のほどよろしくお願い致します。

422 ：デフォルトの名無しさん：2007/05/16(水) 06:57:14

>>421
ソースが shift-jis だってんなら INPUT_ENCODING=Shift_JIS だろ。

423 ：デフォルトの名無しさん：2007/05/16(水) 10:48:18

手元のDoxyfileにはinput-encodingなんてないのだが。
で、input_filter="iconv -f eucjp -t cp932"、use_windows_encodig=yes、output_language=japaneseで使ってるが。
#doxygenはcygwinので、バージョンは1.5.1。

424 ：デフォルトの名無しさん：2007/05/16(水) 11:15:06

INPUT_ENCODING は 1.5.2 で追加されてる。
VB 使いが言う shif-jis は cp932 が正解だろうな。

425 ：423：2007/05/16(水) 11:21:47

>>424
情報THX。ちょっとリビジョン上げてくるわ。

426 ：423：2007/05/16(水) 11:50:37

がーん、未だcygwin版がリリースされてなかったw
#RedHatNetworkは1.3.9.1のままだし。

今回(1.5.2)の変更点はUTF-8対応のほか、C++/CLI対応だとか随分Win使い寄りのような。
件のinput_encodigやdoxyfile_encodingが追加されたと同時にuse_windows_encodingが無くなったようなので、
私のところでは進行中のプロジェクトのDoxyfileをいくつか修正する必要がありそうです。
#逆に、rtfとtexのencodingをわざわざ変えなくて済むようになるなら嬉しいけれど。

427 ：デフォルトの名無しさん：2007/05/16(水) 23:22:19

1.5.1 と 1.5.2 の間で互換性を失ってるのは甚だ遺憾。

428 ：421：2007/05/17(木) 02:03:27

会社から書き込めないので遅くなりましたが、
>>422様の仰るとおり
INPUT_ENCODING=Shift_JIS
input-encoding=C:\vbfiltervbfilter.bat C:vbfilter\tools
にして見た所VBのソースが文字化けせず正常に出力される事が確認できました。
ありがとうございました。

と言うかこんな事に気付かない俺ってダメすぎですorz
的確な突っ込みありがとうございました。

429 ：デフォルトの名無しさん：2007/05/17(木) 10:27:21

つーか、それでも書き間違える(写し間違える)辺りがなんとも。

430 ：デフォルトの名無しさん：2007/06/21(木) 11:08:45

今まで特にコメントのスタイルとか自分では決めず
コメントを書いてきたんだけど、やっぱりそれじゃ
後から見てばらばらで気持ち悪いので、何らかの
ドキュメント自動生成ツールに従った形で書こうと思っています。
doxygen / javadoc / phpdocumentor などのツールが
あるようですが、書式はそれぞれ異なるんですよね？

スレタイに doxygen / javadoc / phpdocumentor とかの文字列が
なかったから検索に手間取っちゃったよ・・・

431 ：デフォルトの名無しさん：2007/06/25(月) 10:46:20

DoxygenにはJavadoc互換モードがあるからどっちかにあわせておけばいいんじゃない?
#phpのは知らない。

432 ：デフォルトの名無しさん：2007/06/25(月) 12:22:53

>>430
その3つなら、PHPとJava使うときはそれぞれの、他はDoxygenでいいんじゃね。

433 ：デフォルトの名無しさん：2007/06/25(月) 20:30:05

sandcastleでC++用のものも作れるんでしょうか？

434 ：デフォルトの名無しさん：2007/07/06(金) 01:22:50

doxygen(Ver1.5.2)とHTML Help Workshopを使って、
Windowsヘルプを作成しているのですが、索引が
どうしても文字化けしてしまいます。
INPUT_ENCODING = Shift-JIS
DOXYFILE_ENCODING =UTF-8
と設定し、ページに関しては文字化けは解消された
のですが… 何か解決策があれば教えてください

435 ：デフォルトの名無しさん：2007/07/28(土) 08:38:52

doxygen 1.5.3 age

436 ：デフォルトの名無しさん：2007/08/12(日) 01:05:32

>>430
doxygen ではよくこの書き方が紹介されているが、個人的にあまりおすすめしない。
/*!
@brief メソッドの説明
@param p 引数の説明
@return 戻り値の説明
*/
・複数行コメントは一括コメントアウトの邪魔になるから
・実コードで引数が変更になると Doxygen の内容も変更しなくちゃいけなくなるから
　（つまりコードと Doxygen の２重管理になる）

437 ：436：2007/08/12(日) 01:08:05

じゃあどうやるかというと

//! @brief メソッドの説明
//! @return 戻り値の説明
void hoge(
p //!< p の説明
)
{ ... }

438 ：デフォルトの名無しさん：2007/08/12(日) 01:46:25

Doxygenは警告吐くんだからちゃんとチェックすりゃいいやん。
>437のやり方だってコードとコメント両方メンテすんのはかわらん。多少近くなるが。
あと長い説明を入れにくくなるな。

439 ：437：2007/08/12(日) 01:55:50

>>438
> あと長い説明を入れにくくなるな。
う゛、鋭いな。

440 ：439：2007/08/12(日) 01:56:36

重ね重ねすまん、間違えて age てしまった

441 ：デフォルトの名無しさん：2007/08/12(日) 02:30:53

おれが昔立てたスレが上がってるな。

おまえら、ドキュメントなんて書きたくなきゃ書かんでいいぞ。
例えばWindowsにはヘルプがあるだろう。
けど、WindowsのGUIは洗練されてるから、あんなの読まなくても判るよな。
判らん奴もいるが、どうせそいつらはヘルプの読み方すら判らんアホだし、
付き合うだけ無駄だろう、と。こういった無茶な主張も今や世間が味方だ。
つまりウィンドウの操作なんて、もはや一般常識なのだ。凄い時代になった。
この概念を突き進めていけば、ユーザーはプログラムの画面を見れば、
何をすべきなのか判るという事だ。洗練されたGUIによって、プログラムと、
ドキュメントは融合を果たしたわけだ。
画面見て使い方が判らないプログラムはゴミと同じ。(これはGNU製に多い)
いや、むしろ今の時代は判らないとのたまう人間の方が、立場は下なのだ。
「ドキュメント見なくても判ります」
おまえら、この言葉を吐く自信はあるか？

442 ：デフォルトの名無しさん：2007/08/12(日) 02:56:38

>>441
GNU の作った GUI 製品って、何かあったっけ？

443 ：デフォルトの名無しさん：2007/08/12(日) 04:59:50

>>441
> WindowsのGUIは洗練されてるから

笑うところですか？

444 ：デフォルトの名無しさん：2007/08/12(日) 05:11:08

いちいち人に聞かないと笑うところも判らない、と。

445 ：デフォルトの名無しさん：2007/08/12(日) 13:51:49

>>437
void hoge( //! @return 戻り値の説明
ついでにここまでやろう

446 ：デフォルトの名無しさん：2007/08/12(日) 13:53:32

>>441
どこ立て読み？

447 ：デフォルトの名無しさん：2007/08/12(日) 16:57:19

＞＞４４２
ＧＴＫ＋

448 ：デフォルトの名無しさん：2007/08/12(日) 17:46:54

>>447
それは GUI 製品とは言わんだろ。

画面見ただけで GTK+ の使い方がわかったら神だな。

449 ：デフォルトの名無しさん：2007/08/12(日) 21:34:45

Glade
Sylpheed

450 ：デフォルトの名無しさん：2007/08/12(日) 22:09:55

>>449
そいつらは GPL でライセンスされてるだけで GNU 製とは言わんのじゃないか？

もしかして >>1 や >>441 の言ってる GNU 製ってのは GPL でライセンスされてる
製品ってこと？それなら作者もバラバラなはずだから、ただの偏見だね。

451 ：デフォルトの名無しさん：2007/08/12(日) 22:44:33

>>441
見ただけで処理がわかるとか
どんだけ紙プログラマなのｗ
ユーザがそんなに凄けりゃ俺たち要らない子だよね（・ω・

452 ：デフォルトの名無しさん：2007/08/12(日) 22:49:21

GNU製ってったらGIMPは？
あれはフォトショのコピーUIな気もするが。

453 ：デフォルトの名無しさん：2007/08/12(日) 23:10:29

つってもGIMPがもとでGTKが生まれたわけだが
今更Cでオブジェクト指向ゴッコかよ
と思わないでもない

454 ：デフォルトの名無しさん：2007/08/12(日) 23:44:15

仮にライブラリのインターフェースをC++にしたとして、
使う人間の方にしわ寄せがくる。DLLにしたくてもABIの問題もあるし。
COMやQTは難解すぎる。
C++はプログラマのフロントエンドとしてのみ使うべきだろう。

455 ：デフォルトの名無しさん：2007/08/12(日) 23:49:25

GNUか忘れたけど、OpenGLなUNIXのライブラリで、
失敗すると勝手にexitやabortするアホなのがあった。
勝手に終わらすなや。straceなかったら死んでた。

456 ：デフォルトの名無しさん：2007/08/13(月) 01:11:07

wxD

457 ：デフォルトの名無しさん：2007/08/13(月) 12:02:32

話を戻そう。

>>436
＞・複数行コメントは一括コメントアウトの邪魔になるから
一括コメントアウトってなに?

ソース管理の原則からは、不使用コードは#ifで囲ってしまうべきであり/* */や//は使うべきではない。
まして、基本的にリリース時には残さないべきなので、複数行コメントを忌避する理由はないと思う。

458 ：デフォルトの名無しさん：2007/08/13(月) 22:07:06

ソース「管理」の原則からは、ね。

でも実際に集中して作業してるときって /* */ 使わないか？
#if #endif より入力しやすいと思うんだが。
ついでに、古いコーディング規約が改定されずに使われる場合、
「VSS でチェックインするソースには原則として /**/ を含まないこと」
みたいな決まりが未だにまかり通る現場もあるんでは？（←ウチだけか？）

>> // は使うべきではない。
おまえんとこは１行コメントも #if なの？

459 ：デフォルトの名無しさん：2007/08/13(月) 22:11:15

>>458
/**/を使ってはならないという規則で/**/でコメントアウトするのは
ナンセンスな気がするが……
もっと言うと、/**/でコメントアウトするときに障害になるから
/**/を使うなということか

あまりにナンセンスすぎて意味がよくわからないな

460 ：デフォルトの名無しさん：2007/08/13(月) 22:24:42

>>459
こんな些細なネタで話を伸ばしたくないんだが。

/**/ は作業中のみ一時的な目的に使うべし、
チームメンバーに公開するソースからは /**/ 無くすべし、
当然使わないコードは消すべし、
一時的に残すなら #if ～ #endif を使うべし。
ということでまぁ折り合いがついてる。

それより、
>> // は使うべきではない。
> おまえんとこは１行コメントも #if なの？
についての解答が欲しい。あんまりコメント書かない習慣ってことか？

461 ：459：2007/08/13(月) 22:34:47

>>460
俺は上の人とは違う（はじめて書き込んだ）ので、上での話を
俺に聞かれても知らん。
俺のことを言えば、//を禁じるのも/**/を禁じるのもナンセンスにしか
思えない。

462 ：デフォルトの名無しさん：2007/08/13(月) 22:42:06

>>461
人違いスマソ
大人しく 457 からの回答を待つよ

463 ：デフォルトの名無しさん：2007/08/14(火) 00:37:35

457ではないけど、コードの無効化に//を使うなって事じゃない？
//f(a, // aのコメント
//b, // bのコメント
//c) {// cのコメント
//}

/*
f(a, // aのコメント
b, // bのコメント
c) {// cのコメント
}
*/
↑つまりこんなことするなって？（こんなことするか？）

#if 0
f(a,b,c) {
}
#endif

>>458
/* */て右手だけでシフト押したりするから入力しづらくね？
手前のキー使うから爪切ってないと辛い
#if 0
#endifのが気持ち早い

464 ：458：2007/08/14(火) 00:58:23

>>463
が紹介したような使い方は稀だけど、無効化した理由を添えることはあるだろう。

// int i = func();
int i = func2();
// ↑×××により○○○に変更。

/* */ の入力にシフトは使わん。テンキーについてるやつを使う。

465 ：デフォルトの名無しさん：2007/08/14(火) 02:00:54

#if で無効化しておいて理由をコメントで添えずにコミットすることを禁止すべきだろう。

466 ：458：2007/08/14(火) 10:24:32

㌧　なるほど

467 ：457：2007/08/14(火) 11:04:13

＞ソース管理の原則からは、不使用コードは#ifで囲ってしまうべきであり/* */や//は使うべきではない。
読み難かったかな。
不使用コードをコメントアウトする目的で、/* */や//は使うべきではないということね。
その目的で//を使うと、例えばリリース前に消したくても通常のコメントと区別がつきにくいので消し損ねかねない。
#ifならgrepでの検出も簡単だろう。

って、>465が書いているね。更には、リビジョン管理しているなら残すべき理由もないはずだが。

468 ：デフォルトの名無しさん：2007/08/14(火) 22:41:53

a = b;
/*
c = d;
*/
e = f;

↑こうなってるときに

/*
a = b;
/*
c = d;
*/
e = f;
*/

↑あとからこんなことする馬鹿がいるからじゃね？

469 ：デフォルトの名無しさん：2007/08/15(水) 03:51:34

>>468
誰に向けて書いたのか知らないがそれはコンパイルエラーだから論外

470 ：デフォルトの名無しさん：2007/08/18(土) 03:26:18

>>468程度でも見難いと思う程度の脳味噌ですが…

471 ：デフォルトの名無しさん：2007/08/22(水) 00:13:17

/* */ とか #if #endif でコメントアウトされてると、grepでコードを引っかけたときに、
それが使われているコードなのかコメント化されているコードなのかがgrepの結果からだけでは分からない。
てなわけでうちでは // だけ使うことになってる。

472 ：デフォルトの名無しさん：2007/08/22(水) 11:30:55

>>471
だからこそ、リリース版のソースにコメントアウトされたコードを残してはいけないのです。

473 ：デフォルトの名無しさん：2007/08/23(木) 01:19:20

当社では、コードを修正する際に修正前のコードをコメントアウトしてソースに残しておくことが
規則で定められてるんだけど、もしかしてレア？

474 ：デフォルトの名無しさん：2007/08/23(木) 01:22:00

ＳＶＮとかＣＶＳとかは？

475 ：デフォルトの名無しさん：2007/08/23(木) 01:50:24

>>473
いや。よくある糞規則。

476 ：デフォルトの名無しさん：2007/08/23(木) 05:59:57

最悪だな

477 ：デフォルトの名無しさん：2007/08/24(金) 01:10:24

>>473ごく普通のことです…orzｷﾀﾈｰ

478 ：デフォルトの名無しさん：2007/08/24(金) 10:56:27

まさか、コメントアウトされた行も含めて行数で金取ってたりしないよな。

479 ：デフォルトの名無しさん：2007/08/24(金) 11:33:09

行数で計算して金をとってる所なんてあるの？見たこと無い。COBOLとか？

480 ：デフォルトの名無しさん：2007/08/24(金) 11:46:27

>>479
Cでも未だあるらしいよ。

481 ：デフォルトの名無しさん：2007/08/24(金) 22:18:51

目安としてステップ数はなくても、n万行のコードって今でも言うでしょ。

482 ：デフォルトの名無しさん：2007/08/24(金) 22:45:51

言わない

483 ：デフォルトの名無しさん：2007/08/25(土) 14:35:46

某上場企業のシステムのリメイクを請け負ったけど
元のがループ使わずコピペでシコシコ行数稼いでいるプログラムがあった
マジで

484 ：デフォルトの名無しさん：2007/09/03(月) 22:19:04

>>479
F痛

485 ：デフォルトの名無しさん：2007/09/04(火) 07:28:56

テンプレートとかgenericsは敵だな。型の分だけ、コード増やせない。

486 ：デフォルトの名無しさん：2007/10/27(土) 18:26:59

Doxygen 1.5.4 age

487 ：デフォルトの名無しさん：2007/10/28(日) 13:23:14

よく、日本人は罫線をやたらと使いたがるって話があって、
たしかに、excelで、罫線使いまくったドキュメントって書くのが面倒なんだけど、
かといって、日本式のそういうドキュメントしか見たことないから、罫線なしで
かっこいいドキュメントというのが想像できません。

外国で使われてるドキュメントのサンプルみたいのを見れるところってありませんかね。

488 ：デフォルトの名無しさん：2007/10/28(日) 20:18:16

>>487
米のミドルウェアをいくつも使ったけど、そのへんのオープンソースのよりもショボい感じ。
オープンソースのをいくつも見ればいいと思うよ。

489 ：デフォルトの名無しさん：2007/10/29(月) 01:30:01

HTMLヘルプで十分て気がする
表示ソフトいらないし、ファイル1個で済むし
*NIXで見れない？
知　る　か

490 ：デフォルトの名無しさん：2007/10/29(月) 02:08:39

>489
つttp://xchm.sourceforge.net/

491 ：デフォルトの名無しさん：2007/10/29(月) 12:29:28

>>487
罫線を使わないこととExcelを使わないことはイコールではないよ。
喩えて言えば、○×をやるのに周りを囲むか(囲こんな形)か、囲まないか(井こんな形)の違い。

492 ：デフォルトの名無しさん：2007/12/08(土) 03:09:44

doxygenで更新履歴をいじった関数に書いて、
todoリストみたいにまとめたいなと思って調べたら、
\xrefitemを使えばオリジナルの\todoができることは、わかったのですが、
関連ページ追加される項目を日付ごとにまとめて並べること方法ないでしょうか?

493 ：492：2007/12/10(月) 02:14:40

以下のようにしてみました。

ALIASES += "history{1}=\xrefitem histories\1 \"更新履歴(\1)\" \"更新履歴(\1)\""

日付でソートできていないし、日付ごとに別ファイルになってしまいます。orz
もっとよい方法は無いでしょうか?

494 ：デフォルトの名無しさん：2007/12/30(日) 02:14:53

ドキュメント管理が破たんしてる業務システムの保守をやってるんだが、

・機能ごとに、仕様書があったりなかったり
・管理がずさんで、どのファイルが本物の仕様書かわからなかったり
・仕様書が現状の実装と同期がとれてなさそうだったり

てな具合。
で、どうにかせにゃアカンってことで、取り急ぎコード修正・保守作業に
最低限必要なドキュメントだけ、リバースエンジニアリングして書き起こしてる
とこなんだが、作った後の維持管理って、みんなどんな感じでやってる？

495 ：デフォルトの名無しさん：2007/12/30(日) 11:15:07

ソースと同じくCVS管理

496 ：デフォルトの名無しさん：2007/12/30(日) 17:27:36

市役所の情報システム部門に勤務している人って居る？

497 ：デフォルトの名無しさん：2008/01/02(水) 20:27:53

市役所のシステム部門つっても、市職員がいる「○○市情報××課」みたいな
市役所ネイティブの部署と、運用を委託されてる会社の人が常駐している実務
部隊の２通り取り方があるわけだがどっち？

498 ：デフォルトの名無しさん：2008/01/09(水) 12:59:45

DOXYGENだが、1.5.2以降、内部ユニコード処理になって、入力ファイルと
出力ファイルのエンコード指定ができるようになっているのはいいんだ
けど、言語とエンコードの指定に関係なく生成されたHTMLのヘッダ部分
は、「charset=UTF-8"」なんだが、ガイシュツ？

ブラウザ側のエンコード自動識別のおかげでHTMLドキュメントはうまく
表示できるが、HTML Help CompilerでHTML Helpファイルに変換すると、
インデックス部分の日本語が化ける。

499 ：デフォルトの名無しさん：2008/01/09(水) 16:53:47

生成されたindex.hhcのエンコーディングをUTF-8からCP932(ShiftJIS)に変換して、
hhc.exe index.hhpでおｋ

500 ：498：2008/01/09(水) 19:45:11

>>499
それじゃあ、ツールを使って自動化する意味ないじゃん。

他にも、index.hhpでのフォント指定やら変で、特に1.5.x以降を使う
メリットが見当たらないので、結局1.4.7に戻した。1.4.7は、Japanese
選択しとくと、「charset="SHIFT_JIS"」になる。

HTML Help をコンパイルする前にフォントを変更しても、Doxygenで生成
されるソースコードのページのフォントが変なんだよね。どうもアルファ
ベット部分だけ、無条件にArialになってるっぽい。

501 ：499：2008/01/10(木) 02:54:40

自分はHTMLとPDFを生成できるようにnmake用のMakefile作って自動化してるんだが。
ツール側の対応に頼るのもいいけどさ。

502 ：デフォルトの名無しさん：2008/01/10(木) 06:10:22

すいません、あるWindowsアプリ(制御系)のドキュメントを
作成するよう指示がありました。
ちなみに開発環境はTurboC++。
C++の知識レベルは、入門書１冊読んだ程度。（アプリ開発経験なし）
Doxygen使ってみたのですが、Doxygen対応コメントで作成されてないので
クラス階層とか関数呼出などの図ではイメージできるのですが、
コメントがないので、やってることがさっぱりわかりません。
そういう場合は、やはり、ソース解読しながら、
Doxygen対応コメントをひたすら打ち込むことから始めるべき
なのでしょうか？

503 ：デフォルトの名無しさん：2008/01/10(木) 07:58:38

アプリのなんだからDoxygen関係ないじゃん

504 ：デフォルトの名無しさん：2008/01/11(金) 14:48:40

Doxygen用のコメントを作るには、ある程度解析が必要だから方針としては悪くないと思うよ。
でも、そこで要求されている「アプリのドキュメント」はDoxygenの出力でいいの?
通常はその括りだと基本仕様か機能仕様に類する資料が必要になってくると思うのだけど。

505 ：デフォルトの名無しさん：2008/02/10(日) 21:43:34

Doxygen 1.5.5 release age

506 ：デフォルトの名無しさん：2008/02/11(月) 11:45:18

Doxygen 1.5.6 release age

507 ：デフォルトの名無しさん：2008/02/11(月) 12:09:51

ちょっとまて
ここはDoxygenスレじゃないんだぜ

508 ：デフォルトの名無しさん：2008/02/12(火) 14:02:50

だからといってDoxygen等の各ツール専用スレを建てると
このスレもそのスレも今まで以上に過疎るからやめてほしいぜ

509 ：デフォルトの名無しさん：2008/02/12(火) 14:42:19

いや個々のツールの使い方はかなり無関係だろこのスレ

510 ：デフォルトの名無しさん：2008/02/12(火) 14:47:10

保守代わりってことでいいと思う

511 ：デフォルトの名無しさん：2008/02/12(火) 15:06:37

一ヶ月も放置されてたスレに、自分の意にそぐわないレスが二つ付いただけで
噛み付く奴って何なの？

512 ：デフォルトの名無しさん：2008/02/12(火) 15:33:25

問題は時系列ではなく内容である
「1ヶ月ぶりのレスだから何書いても許す」というほうが不条理

513 ：デフォルトの名無しさん：2008/02/12(火) 15:35:41

不条理もへったくれもないだろ。スレ違いと言うほど外れた内容じゃないんだから。
敢えて>509の言うように「個々のツールの使い方」は無関係だとしても、「個々のツールの情報」は無関係じゃないだろ。

514 ：デフォルトの名無しさん：2008/02/12(火) 15:46:47

>>512
何書いても許すなんて言ってないだろ、ボケ
「お前の意に沿わないレス」で噛み付くなって言ってんだ

515 ：デフォルトの名無しさん：2008/02/12(火) 16:05:15

お前の意に沿わない「お前の意に沿わないレス」へのレスに
噛み付くなともいへり。

516 ：デフォルトの名無しさん：2008/02/12(火) 16:06:10

すまん、あまり面白くなかった。

517 ：デフォルトの名無しさん：2008/02/12(火) 16:15:09

よし、いいぞもっとやれ、もっと罵りあえ！

いいですか、↑これがどうしようもないレスという物の見本です

518 ：デフォルトの名無しさん：2008/02/12(火) 16:17:58

まあ久しぶりににぎわってよかった。

↑これはどうかな。優等生過ぎてどうしようもない？

519 ：デフォルトの名無しさん：2008/02/12(火) 22:50:57

ﾄﾞｷｭﾒﾝﾄ書くのﾒﾝﾄﾞｸｾｪ・・・
そもそも何を書いていいのか分からんのだよ

520 ：デフォルトの名無しさん：2008/02/12(火) 23:44:47

>>519
大丈夫だ。どうせ誰も見ない。

ぐらいの気持ちで書いてまつ。
本当に皆が必要な内容ならそんな悩まなくても書けるよ。

521 ：デフォルトの名無しさん：2008/02/13(水) 01:27:10

「～したら期待したとおりにうごかねーぞｺﾞﾙｧ」ときた時に
「ドキュメントは読みましたか？ﾌﾌﾝ」とするために書く。

522 ：デフォルトの名無しさん：2008/02/13(水) 23:08:46

ソースコードにドキュメント付けするときには、
とりあえず日付を真っ先に書くようにしている。

ほかの文章は後からでも書けるけど、
こればっかりは後から思い出そうとしても思い出せない。

523 ：デフォルトの名無しさん：2008/02/15(金) 15:13:16

書いてすぐコミットしようよ・・・

524 ：デフォルトの名無しさん：2008/02/16(土) 12:59:06

>>522
ついでに天気とその日の主な事件も書いとけ

525 ：デフォルトの名無しさん：2008/02/26(火) 20:56:32

source code に含まれないドキュメントに数学記号使った数式を
書いたら怒られたんだが, なぜ?

526 ：デフォルトの名無しさん：2008/02/26(火) 23:47:14

>>525
理由も聞かなかったのか？馬鹿

527 ：デフォルトの名無しさん：2008/02/27(水) 00:17:20

>>526 意味がわからんとゆわれた

528 ：デフォルトの名無しさん：2008/02/27(水) 00:26:10

プログラマなら常識ですと言ってやりたいなｗｗｗｗ

529 ：デフォルトの名無しさん：2008/02/27(水) 00:26:46

>>527の意味もわからんわ馬鹿

530 ：デフォルトの名無しさん：2008/02/27(水) 15:40:49

>>437
俺も重複を避ける為にそう思った。
が、この文法では、@param属性(入力,出力、入出力)が付けられない。これは痛い。
従って、@paramを使わざるをえなかった。

//445
ダメだよ、それじゃ。パッと見でもおかしいし、実際変な表示になるよ。

531 ：デフォルトの名無しさん：2008/03/05(水) 23:50:08

マニュアル・手順書を作るのに、使うのはWord？Excel？

俺はExcel派。
Word使うヤツの気が知れない。

要するに、あとで文章直すときに改行がExcelだと
大変だってだけの話でしょ？

レイアウトは断然Excel優位だよね。

532 ：デフォルトの名無しさん：2008/03/05(水) 23:52:51

まだEXCEL使い奴いるんだな

533 ：デフォルトの名無しさん：2008/03/06(木) 09:04:30

つられませんから。

でもスタイル指定しないWordはひょっとしたら
確かにExcelよりクソかもしれない。

534 ：デフォルトの名無しさん：2008/03/06(木) 16:21:43

まあ、Excelの方が向いてるドキュメントはあるわな。

535 ：デフォルトの名無しさん：2008/03/07(金) 01:26:50

>>531
> マニュアル・手順書
にかぎるんだったら, エディタで書いた平テキスト
エンドユーザー向けのマニュアルは別部門が作る
図面ほしいって言われたら、CAD 図面

# 新規ハード使う組み込み系の仕事がほとんどだが

536 ：デフォルトの名無しさん：2008/03/12(水) 18:34:18

ここはdoxygenスレじゃない事は分かっているのですが・・・ちょっと質問。

関数仕様書を作るのにdoxygenを使おうとしています。 ver1.5.5を使っている
のですが、HTML出力は上手くいくものの、rtf出力になるとUTF-8でエンコード
されていて、テキストエディタでは日本語が読めるのですが、Wordやワードパッド
では文字化けして読めません。これではRTF出力する意味がありません。

DoxyWizardでは出力、入力ともShift-JISに設定しているのですが・・・(当然、
ソースのコメントはShift-JISです)

一体何がいけないのでしょうか？

537 ：デフォルトの名無しさん：2008/03/12(水) 21:54:59

SHIFT-JIS
↓
SHIFT_JIS

538 ：536：2008/03/13(木) 09:27:00

SHIFT_JISにはなっていました。エンコード設定の所にカーソル合わせると
「gnuのlibiconv使ってるからそこのページ見ろや」みたいな表示が出るので
そこを見てコピペしたからだと思います。

HTMLはちゃんと表示出来るのにRTFがダメなのが良く分かりません。

539 ：デフォルトの名無しさん：2008/03/13(木) 13:50:29

CP932は試した？

540 ：536：2008/03/14(金) 18:08:47

CP932でもダメのようです。
どうも、エンコード方式を指定するバージョンでは全てダメのようで。
具体的には1.5.2からはダメ。

仕方ないので1.5.1以前を使おうかと思います。ソースいじってなんとかする
スキルはないし。

あと、ついでにもう気づいた事。@paramコマンドで[in][out]表示が出来ますが、
HTMLでは問題ないものの、RTFでは何故か表示できません。

なぜRTFにこだわるかと言うと、提出物としてはHTMLよりもWord文書の方が良い
のではないかという事です。RTFならそのままwordで読めるし、DOCに直すにしても
ほとんど手直しの必要がないですからね。

まぁ、Word出力するなら商用ツール使えって事なのかなぁ・・・でも、ウチの会社
そんなに余裕ないし。

541 ：デフォルトの名無しさん：2008/03/14(金) 20:30:26

defaultcharsetと合ってないor設定されていないんじゃないかな

542 ：デフォルトの名無しさん：2008/03/24(月) 11:25:04

>>536
うちじゃどうしても日本語が必要なときはTeXで出して、pdfに落として提出した。
そうでないときは、全部英語にしておいた。
そうか、1.5.1ならRTFに日本語を出せたのか……

543 ：デフォルトの名無しさん：2008/04/07(月) 23:38:23

ソースにdoxygenのコメントのテンプレートを挿入してくれるツールって無いですか？
たとえば

int f(int x)
{
…
}

というソースがあったら

/*!
*
* @param x
* @return
*/
int func(int x)
{
…
}

のような感じでコメントを挿入してくれるとありがたいです。

544 ：デフォルトの名無しさん：2008/04/12(土) 21:56:16

>>543
よし、売ろう

545 ：デフォルトの名無しさん：2008/04/13(日) 16:41:20

>>543
Visual Studioでの開発ならマクロ組めば出来るんじゃないかな

546 ：デフォルトの名無しさん：2008/04/28(月) 19:31:50

ネットワークプロトコル説明するのに、状態遷移図書いて提出したら
「意味がわからん！！！書き直してこい！！！」
と言われてしまったんだが、おまえらどうやって説明してますか？

# 一応、説明文は遷移図一枚につき5ページくらいは書いたんだが…

547 ：デフォルトの名無しさん：2008/04/28(月) 19:34:27

>>546
＞# 一応、説明文は遷移図一枚につき5ページくらいは書いたんだが…
説明文をだらだらと長く書きすぎたんじゃない？

548 ：デフォルトの名無しさん：2008/04/28(月) 19:42:13

だったら図だけで分かってほしかったよorz

これじゃわからんって言うから、書き足していったらこうなった

どう説明すりゃいいんだ？
縦線ひいて斜め矢印か？
例外だらけになるやないか！！！

549 ：デフォルトの名無しさん：2008/04/28(月) 19:46:17

>>548
怒られたのに何がダメだったのか聞いてはないの？

550 ：デフォルトの名無しさん：2008/04/28(月) 19:50:19

>>548
箇条書きにした？

551 ：デフォルトの名無しさん：2008/04/28(月) 19:51:26

>>549
もっと詳しく書けっていったから詳しく書いたんだが、ついでに数式まで交えて…
「例をだせや！！！」っても、「はじめてなんでありません」と…

552 ：デフォルトの名無しさん：2008/04/28(月) 19:52:27

>>545
そういえば、VSってソース解析する上にマクロからアクセスできるんだったな。
ドキュメント自動生成マクロなんかあってもよさそうなのにな。
何とか工房がそうなのか？

553 ：デフォルトの名無しさん：2008/04/28(月) 20:10:39

>>551
相手が理解できない点を、推測じゃなくて、ちゃんとヒアリングするのは無理なのか?
あと、説明するときは、いきなり本物じゃなくて、ミニマムセットで理解できるかどうか確認するとか。
そこらへんにギャップがあると、「それじゃわからん」vs「ではどう書けと」の対決になるような希ガス。

554 ：デフォルトの名無しさん：2008/04/28(月) 21:32:33

プロトコルなんだから、シーケンス図？（自分対相手でメッセージを線で表現した奴）も
必要なんじゃない？

555 ：デフォルトの名無しさん：2008/04/28(月) 22:06:01

自分<-- メッセージ -->相手

こうかｗ

556 ：デフォルトの名無しさん：2008/04/28(月) 23:24:10

通信プロトコルならシーケンス図がいいんじゃないか？
状態遷移図と突き合わせできるように書けばOK

557 ：デフォルトの名無しさん：2008/04/28(月) 23:33:37

>>556
しかし、シーケンス図だと条件分岐がすごく書きにくくない?

558 ：デフォルトの名無しさん：2008/04/29(火) 01:20:36

パターン別に何種類か書いたらよかろうが

559 ：デフォルトの名無しさん：2008/04/29(火) 01:28:42

組み合わせ爆発しなきゃそれでいいかもしれんが……。

560 ：デフォルトの名無しさん：2008/04/29(火) 12:28:52

プロトコルってのは「やりとりの規約」だかんな
やりとりに出てくるもの全てを図に入れて，なおかつどんなやり取りが行われるのかを書かないといけないんでないかい？
でもヒアリング一発ですみそう

561 ：デフォルトの名無しさん：2008/04/29(火) 12:46:13

rfcでも参考にして書けばいいんでない？

562 ：546：2008/04/29(火) 14:38:51

>>561
RFC を参考にしてではなく RFC 提出できるくらいまじめに書いた

だけど、定義してるのはプロトコルなんで
「実装する奴が理解でない！！！」

結局, フローチャート書きまくりだとか数式無しだとかじゃないと
駄目らしい

だけどさ、状態遷移図をコーディングレベルに落すのは
「あんたらの仕事じゃねぇの？？？」 >>25才位のクライアントの担当者

# つか、ステートマシンとか習わかったのか？

563 ：デフォルトの名無しさん：2008/04/29(火) 14:57:59

>>562
もしかして日本語がやばいんじゃないか？

564 ：546：2008/04/29(火) 15:12:04

>>563
おぉ、そうかもしれん＞俺の日本語 Www
だれどさ、院出てから、10年以上この業界に巣食ってるけど、
いままでお目にかかったことがない＞こんなクライアント

565 ：デフォルトの名無しさん：2008/04/29(火) 15:23:28

クライアントは何屋さん？

566 ：546：2008/04/29(火) 15:44:01

>>565
今まで、地方自治体外郭団体向けに事務処理ソフト作って{る|た}会社
>>564 書く直前に
「理工系の知り合いに聞いたら、うちが悪かった」
って，電話入ってきた。
まぁ、>>564 ただの愚痴だし、確に、俺も悪かった思うが………
こんなに、言語の差があるもんなのか？

567 ：デフォルトの名無しさん：2008/04/29(火) 16:41:31

とりあえず日本語でおｋ

568 ：デフォルトの名無しさん：2008/04/29(火) 16:46:09

まぁ、独自プロトコルを定義した仕様書を今まで見たことないんだろうね。
いつまでも自分流儀でやって、愚痴たれながしとけばいいよ。

569 ：デフォルトの名無しさん：2008/04/30(水) 00:07:17

事務処理オンリーだった会社じゃ通じなくても不思議はない。
不思議はないが不甲斐ないな、そこ。

570 ：デフォルトの名無しさん：2008/04/30(水) 02:15:31

>>543
VS2005ならDoxyCommentがいいんじゃね
書式もカスタマイズできるし

571 ：デフォルトの名無しさん：2008/04/30(水) 02:52:52

正直、ドキュメントが読めない
ＤＢの構成とか設計書とか。
「読んだら分かる」っていつも言われるんだけど、
どうしたらいいかな。

572 ：デフォルトの名無しさん：2008/04/30(水) 03:18:04

>>571
落ち着いてジックリ読んでみな。

573 ：デフォルトの名無しさん：2008/04/30(水) 10:43:42

>>566
そう言う所は、得てして「うちはどこそこの仕事をしているんだ」って妙な自負があるから
こっちが何を書いてもクレームつけるよ。謝罪の電話があっただけでもましな方かも。
# うっかりしていると、同じドキュメントを「概要」と「詳細」と「解説」の3バージョン作る羽目になったり。

574 ：デフォルトの名無しさん：2008/04/30(水) 13:11:38

これはいい勉強になるスレ

575 ：デフォルトの名無しさん：2008/05/01(木) 21:02:41

>>571
ドキュメントは読めるようになったほうがいいよ。人に
頼ることなく進む力がぐんと増える。(ドキュメントに
頼る時点で、というのは無しで)

どうしたらいいかと言われると解答に困るんだけど、
日頃から疑問に思ったことがあれば、まずドキュメントに
目を通すという習慣をつけてみたらどうだろう。

java でプログラミングしてて分からないことがあったら
まず javadoc を当たってみて、それでも分からなければ
ぐぐってみたりとか。
ツールのインストールの時も、まずは付属ドキュメント
(README, INSTALL みたいなやつ) に目を通すとか。

576 ：デフォルトの名無しさん：2008/05/02(金) 10:31:47

それ、「～ほうがいいよ」ってレベルじゃなくて、「～できなきゃダメ」のレベルだと思う。

577 ：デフォルトの名無しさん：2008/05/03(土) 13:36:57

>>546
遷移図は全体を出さずに、

　ほげをするとBになります
　A→B

　ここでげほをするとCになります
　A→B→C

　ここでほれをするとAになり、やりなおしできます
　A→B→C┐
　 ←──┘

まあなんだ、たぶん図は崩れたと思うけど、インクリメンタルに
説明と共に図を成長させると理解してもらいやすい。

パワポのアニメで説明するとわかったきになるのに、
紙に出した同じ資料がわかりにくいのも同じ理由だと思う。

578 ：デフォルトの名無しさん：2008/05/06(火) 04:58:29

>>572
>>575

遅くなったけど、ありがとう。
疑問を持ったら人に聞くクセをなくすように
がんばります。

579 ：デフォルトの名無しさん：2008/05/08(木) 17:47:02

今度開発の仕事やらせてもらう事になりました。
その前に勉強として、仕様書作ってプログラム作れって上司から
言われました。
プログラムは作ったことあるんですが、仕様書なんて作ったことありません。
常識的に考えたら、基本設計書、概要設計書、コード設計書とか全部作るべきでしょうか？

580 ：デフォルトの名無しさん：2008/05/08(木) 20:27:21

上　司　に　聞　け

581 ：579：2008/05/08(木) 23:52:12

>>580
言葉足らずですみません。
仕様書って何の事か聞いたんですが、自由に作っていいって言われたんです。
自由に作れと言われたら基本的な概要、機能とか画面構成など書けば仕様書としては
成り立つんだと思うんですが、いかんせん初めての経験なのでどのように書いたらいいか
わからないんですよね。
社会人の常識として設計書の本読んで基本設計書、概要設計書
など全ての設計書を作るのが妥当なのかという質問です。

582 ：デフォルトの名無しさん：2008/05/09(金) 00:08:07

単なる練習プログラムなんだから概要からでいいんじゃね

583 ：デフォルトの名無しさん：2008/05/09(金) 03:44:01

上司乙ｗ

584 ：デフォルトの名無しさん：2008/05/09(金) 08:08:02

>>581
疲れたので途中で止めとくけど、こんな感じで読める読み物を作ればおけ。

ゴールの定義
・どういう背景があり（どういう歴史があり何で困っていたのか）
・何を実現したいと考えています（作ったものを使うことで得られると期待される効果のこと）
・このために何々をするものを作ることにしました

全体構造
・大きな制約条件として～がある中で（納期、コスト、現状からくる技術?%A

585 ：デフォルトの名無しさん：2008/05/09(金) 08:09:41

あれ？途中で切れてしまった・・・
書き直すもの疲れたので諦めるすまん>>581

586 ：デフォルトの名無しさん：2008/05/09(金) 09:40:43

骨組みでこの程度がわかれば良い。
・なんで作ったのか
・それを使ってどういう効果が期待できるか
・必要とする環境
・入力は何か
・出力は何か

競合するプログラムが既にある場合を除いて、
最初はどういう機能がとか、画面が云々とかは不要。
必要だといわれたら付け足していけば良いはず。
読む側にとってどうでもよさそうな事は極力避ける事。
つーか多分作ったのを後で添削するのが
意図なわけだから、あまり時間掛けると嫌われるぞ。

587 ：581：2008/05/09(金) 16:21:25

>>586
入力、出力ってどういう意味ですか？
A4用紙一枚にまとめるのは変でしょうか？

588 ：デフォルトの名無しさん：2008/05/09(金) 16:40:36

>>587
入力も出力もないプログラムは役に立たないだろう
記述が必要十分なら一文字にまとまっていても構わないぞ

589 ：581：2008/05/09(金) 17:00:35

>>588
もしデータベースを扱うプログラムだったら、
どのようなデータを登録して（入力）、どのような形で表示するか（出力）
簡単に言えばこのような事でしょうか？

590 ：デフォルトの名無しさん：2008/05/09(金) 20:04:08

電卓のイメージなら簡単だろ？
ユーザーが入力して、プログラムがそれを計算する。（出力）

591 ：デフォルトの名無しさん：2008/05/10(土) 01:11:34

上司から言われたことの真の目的を明確にして、その目的を達成するためのプロセスや成果物を決めたらどうだろうか？
社会人の常識とかじゃなくて、目的から考えた方がよいのでは

592 ：デフォルトの名無しさん：2008/05/10(土) 10:46:22

クラスの仕様の概要って、どこまでが概要ですか？

593 ：デフォルトの名無しさん：2008/05/10(土) 10:52:50

>>592
クラス仕様の詳細じゃない部分

594 ：デフォルトの名無しさん：2008/05/10(土) 11:23:40

>>592
・そのクラスの責任範囲と全体の中での役割
・超簡単なサンプル使用例
・データの流れと関与する主要APIを図示したもの（ポイントとなるクラスの場合）

これが１ページで欲しい所。

595 ：デフォルトの名無しさん：2008/05/26(月) 16:40:33

doxygenについて質問したいのですが、専用スレが無いようなのでこちらでさせてください。
PC:Windows XP
コンパイル方法:Visual Studio 2005のコマンドプロンプト上で、下記の命令をする
　make msvc
C:\doxygen1.5.5 に doxygen1.5.5.src.tar.gz を解凍した中身を置きました。
C:\doxygen1.5.5\src　のソースをいじって、コンパイルしましたがエラーが出てしまいます。
エラー内容
----
　link /NOLOGO /LIBPATH:..\lib /SUBSYSTEM:console /OUT:..\bin\doxygen.exe
　@C:\DOCUME~1\AA\LOCALS~1\Temp\nm2E.tmp
　～
　doxycfg.lib(portable.obj) : error LNK2019: 未解決の外部シンボル __imp__libiconv_open が関数 "void * __cdecl portable_iconv_open(char const *,char const *)" (?portable_iconv_open@@YAPAXPBD0@Z) で参照されました。
　～
　..\bin\doxygen.exe : fatal error LNK1120: 外部参照 5 が未解決です。
　NMAKE : fatal error U1077: 'link' : リターンコード '0x460'
----
doxygenのソースのコンパイルは、下記以外に必要なものはありますか？
・Active perl
・GnuWin32のFlex
・Qt
・VC2005
・Microsoft Platform SDK

596 ：デフォルトの名無しさん：2008/05/26(月) 17:33:49

libiconvって書いてあるじゃん。
エラーメッセージぐらい読めるようになったら？

597 ：595：2008/05/26(月) 18:28:33

>>596
ありがとうございます。
iconv.lib,iconv.hがdoxygenのソース内に入っていたのでこれで良いのかと思っていました。
Libiconvをコンパイルしたものと差し替えたら、コンパイルが通過して下記ファイルが出来ました。
　doxygen.exe
　doxytag.exe

598 ：ura2ch.czsoftbank219174032071.bbtec.neta.net：2008/05/26(月) 18:33:08

guest/guest

599 ：デフォルトの名無しさん：2008/05/28(水) 23:41:27

開発の人間なら仕様書を云々言う前に
ソース内のコメントをちゃんと書け！

と思う、インフラ屋は俺だけではないはず。

特にリリース後の修正箇所に対して正確な
コメントが書かれているソースが本当に少ない。

頼むから引数のコメントくらい、まともに書いてくれ・・・・

600 ：デフォルトの名無しさん：2008/05/30(金) 04:18:14

変数名自体を説明にするしかない

601 ：デフォルトの名無しさん：2008/05/30(金) 13:08:41

システムハンガリアンを止めて、アプリケーションハンガリアンにする。

602 ：デフォルトの名無しさん：2008/05/31(土) 00:23:06

>>599
> 特にリリース後の修正箇所に対して正確な
> コメントが書かれているソースが本当に少ない。

これはコミットログやChangeLogの役目だろう

603 ：デフォルトの名無しさん：2008/05/31(土) 13:13:14

> これはコミットログやChangeLogの役目だろう
ソース内のロジックとコメントは分業してるってこと？

ロジックとそのコメント内容が一致してないから
障害対応してるときに頭からソースを読まなければ
ならないってこと。
そして、修正したPGはすでにいないことが多い・・・・

604 ：デフォルトの名無しさん：2008/05/31(土) 17:32:04

コメントとソースを同じくらい価値があるものだと考えるのはいいが
コメントとソースを同じように扱ってはいけないだろ

605 ：デフォルトの名無しさん：2008/05/31(土) 18:51:02

そこまでコメントに期待してないよ。
ただ最初にも書いたけど、表題部の
プログラム名や用途、引数説明すら
まともに書いてないソースが多すぎる
からカキコしただけだ

606 ：デフォルトの名無しさん：2008/05/31(土) 19:19:50

doxyの1.5.6でツリーが文字化けするのって俺だけ？
1.5.5平気なんだけど

607 ：デフォルトの名無しさん：2008/05/31(土) 21:19:45

４コマ漫画で８００ページの取扱い説明書

608 ：デフォルトの名無しさん：2008/05/31(土) 22:24:13

>>603
> 特にリリース後の修正箇所に対して正確な
> コメントが書かれているソースが本当に少ない。

これは「こう修正しました」っていうコメントのことでしょ？
それはまさにコミットログ等の役割
コードからは読み取れない「こういう処理です」っていうのがコメントの役割だと思う

609 ：デフォルトの名無しさん：2008/06/01(日) 01:34:08

>>608
"「こう修正しました」"は
ソース内の修正(変更)履歴のことを言ってる。

610 ：デフォルトの名無しさん：2008/06/01(日) 01:53:13

>>609
そりゃあSCMがない時代の苦肉の策でしょ

611 ：デフォルトの名無しさん：2008/06/01(日) 09:06:34

>>609
バージョン管理使おうぜ

612 ：デフォルトの名無しさん：2008/06/01(日) 11:47:08

>610,611
今、休出でVSS見てるけど、コミットログやChangeLogは存在しない。
各ソースのチェックインコメントは全部一緒で"○○○○更改に対する修正"・・・・
ほかに見るとこあれば教えてくれ。

（インフラ側で作ってる基盤モジュールのアップデート履歴のほうが
詳細に記載している。）

613 ：デフォルトの名無しさん：2008/06/01(日) 17:35:45

>>612
履歴を残そうという意識が作業者に無ければコミットログにも残るわけ無いだろ。
お前んとこのローカルな事情だな、それは。

で、一般的に履歴を残すんならどっちかというとコミットログのほうが適切という話。

614 ：デフォルトの名無しさん：2008/06/01(日) 17:43:21

>>612
コミットログはチェックインコメントと同じ意味
ツールが違うと用語が違う
チェックインコメントが全部一緒だと無意味だと感じませんか？
チェックインコメントは修正内容を記録するのにうってつけだと思いませんか？

615 ：デフォルトの名無しさん：2008/06/01(日) 17:49:07

ソースに履歴コメントされても探すのが大変だし。同時に変更したファイルの関連や前後関係も把握するのも正確に記載するのも困難。
コミットログならすぐ探し出せる。コメント漏れがあっても差分を見つけられる。
コミットログに情報がないというのは、結局コメントの入れ方、運用の問題でしょ。

616 ：デフォルトの名無しさん：2008/06/01(日) 19:27:14

ソースが動かないというのは、結局プログラムの書き方、プログラミングの問題でしょ
みたいな感じに見えた

617 ：デフォルトの名無しさん：2008/06/02(月) 15:25:20

【コメント】doxygen【コンソメ】
http://pc11.2ch.net/test/read.cgi/tech/1212144627/

618 ：デフォルトの名無しさん：2008/07/27(日) 04:43:22

doxygenの話題は禁止

619 ：デフォルトの名無しさん：2008/08/23(土) 14:10:15

http://www.hotdocument.net/
じゃだめかな。

620 ：デフォルトの名無しさん：2008/08/23(土) 18:05:57

これはひどい

621 ：デフォルトの名無しさん：2008/11/17(月) 15:02:59

doxygen,hotdocument,visio

どれがいいだろうか・・・
C++Builder2007なんだけど。どれ対応してるかもまだ調べてないんだ。

とりあえず・・・探すか。

622 ：デフォルトの名無しさん：2009/02/07(土) 11:48:29

詳細仕様の中でBNFを使用したら「意味がわからん」と言っておこられましたorz

何か適当な代替え手段はないでしょうか？

# 何年ソフト屋やってんだ？ BNFくらい読めよ > 某メーカの糞 SE

623 ：デフォルトの名無しさん：2009/02/07(土) 12:29:55

アキバのチョムチョムでやけ酒の飲むしかないね。

624 ：デフォルトの名無しさん：2009/02/07(土) 12:32:07

知らないと読めないんだから確認しなかったお前が悪い

625 ：デフォルトの名無しさん：2009/02/07(土) 13:16:45

BNFの書き方が悪かったんじゃないの？

要所で適切な名前をつけて分割してあれば読みやすいし、
BNF知らなくても直感的にわかると思う。
逆に、１行でだらだら書かれたりすると、いくら正しくても読みづらい

626 ：デフォルトの名無しさん：2009/02/07(土) 14:43:47

学生「意味が分からない．」
先生「意味が分からない．」

627 ：デフォルトの名無しさん：2009/02/07(土) 17:25:11

構文の説明でもオートマトンで図示するのが多いかな

628 ：622：2009/02/07(土) 17:42:31

>>625
条件指定できる設定ファイル用なので、そんなに巨大なツリーじゃない
そもそも, BNF の読み方を知らないらしい

>>627
Pascal の構文定義に使ってある奴？あれって、けっこう一般的なの？
つか、BNF と変わらないような気もするが…

大量の使用例を書くしかないのか？

629 ：デフォルトの名無しさん：2009/02/07(土) 18:58:29

BNFじゃなくてSEFで書かないとだめです

630 ：デフォルトの名無しさん：2009/02/07(土) 20:30:03

理解したいというなら教えてやれば言いと思うけど、単に
xxx *= yyy | xxx yyy
を
項 xxx は、単独の yyy または xxx に続く yyy によって定義されます。
とかの半分機械的な置換で済むかもよ。

631 ：デフォルトの名無しさん：2009/02/07(土) 22:55:31

>622
BNF云々というより、人との付き合い方の問題な気がする
TPOとか判ってないでしょ
他人のオナニー文書を読まされる側の立場にもなってみろ

632 ：デフォルトの名無しさん：2009/02/08(日) 01:39:27

>>631
書き手：「お前のオナニー用エロ文書を書かされる立場になってみろ」
読み手：「他人のオナニー文書を読まされる側の立場にもなってみろ」

不毛な・・・

633 ：デフォルトの名無しさん：2009/02/08(日) 01:52:16

言いたいことがわからない

634 ：デフォルトの名無しさん：2009/03/07(土) 12:45:09

仕様書はどっかの機関が音頭を取って規格化してほしいわ

635 ：デフォルトの名無しさん：2009/03/07(土) 21:27:24

フローチャートは全面禁止してほしい

636 ：デフォルトの名無しさん：2009/03/07(土) 21:52:54

ドキュメントって小説みたいなところがあるよな。
どんなに文字を尽くして書いても、相手の頭にすっと入ってイメージを
作れないと負け。

駄目なドキュメントって、たぶんすべて書いてあるんだろうけど
量ばかり多くてツマラン推理小説みたい。筋の5W1Hがさっぱり見えないで
筋書きを楽しむ以前に何がなんだかわからないオナニーみたいなやつ。

637 ：デフォルトの名無しさん：2009/03/14(土) 03:43:34

彼氏（彼女）のオナニー見ながらオナニー
見せ合いっこはｺｰﾌﾝする

638 ：デフォルトの名無しさん：2009/04/10(金) 18:21:15

あるある

639 ：デフォルトの名無しさん：2009/04/12(日) 14:23:36

俺様要求仕様書と俺様詳細設計書のガチンコ勝負！

640 ：デフォルトの名無しさん：2009/06/13(土) 08:57:14

質問させてください。
学習目的で小さなプロジェクトを立ち上げようと思っているのですが、
各種ドキュメント（基本設計、詳細設計、テスト仕様書等）の雛形、規格のようなものは
どこかで公開されていないのでしょうか？

IEEEって団体が作ったものがあるようですが
無料ですぐに手に入るものではないようです。

他にどこか有名な団体が作成したものがあるでしょうか。
できれば日本語が好ましいです。
よろしくお願いします m(__)m

641 ：デフォルトの名無しさん：2009/06/15(月) 11:53:08

俺みたいな底辺SEはプロジェクト終了と同時に傭兵のように各地に派遣されてるから
行く場所場所でドキュメントの定義やスコープ、はたまた名称まで違ってて毎回混乱・・。
その場所のしきたりに慣れるまでストレスを追わにゃぁならん。
プロジェクトの規模にもよるから当然ちゃ当然だが、ドキュメント類は
大まかな指針のようなものに従って書いてもらいたいし、書きたいわけだ。

どこかの学者様かスーパーＳＥ様あたりが統一規格のようなものを打ち出してくれて、
それが広まってくれれば助かるんだがな。

642 ：デフォルトの名無しさん：2009/06/15(月) 12:47:00

大丈夫、底辺SEがどんなに頑張っても既に採用されている仕様書のフォーマットが変わることはありえないから。
そもそも用語でさえベンダ間で互換性がないんだから、どうしようもないな。

643 ：デフォルトの名無しさん：2009/06/15(月) 16:25:34

ドキュメントは既存フォーマットを改良して作るのが一番てっとり早いわな。
であるならば、新規プロジェクトを起こす場合、最大公約数的な雛形となるべき指針が
存在してもいいはずだと思わんでもない。
ま、下請けが納品する場合はどうあがいても、大手のフォーマットを利用せざるを得んのだろうが・・。

ちょっと探してみたんだが
ttp://www.hotdocument.net/
↑あたりはなにかしらのフォーマットを利用したんだろうか？

644 ：デフォルトの名無しさん：2009/06/15(月) 19:02:04

何を持って良いドキュメントって言うんだ？

普通そこらに転がってるドキュメントって、
＊＊＊このように、できてます！！！＊＊＊が、書いてあるだけで

＊＊＊このように作らなければならない理由＊＊＊が、書いてない。
＊＊＊もっと上の仕様書との連続性もない＊＊＊場合がほとんど。

なので、メンテナンスの役に立たない。

645 ：デフォルトの名無しさん：2009/06/15(月) 21:11:58

>>640
大手ベンダが専門の標準化チーム作ってフォーマットをガリガリつくってんのが現状。
派遣ソルジャーがデータ持ち出さない限り表にゃあ出てこねえよ。

646 ：デフォルトの名無しさん：2009/06/16(火) 06:58:09

IPAの発注者ビューガイドラインとかどうでしょう。
発注者視点ですが、開発者でも使えると思う。

647 ：デフォルトの名無しさん：2009/06/16(火) 14:37:32

これあたりは熟読すればいいんじゃなかろうか？
ttp://www.sage-p.com/process/process.htm
俺めんどくさいから目通してないがｗ

648 ：デフォルトの名無しさん：2009/06/16(火) 17:10:39

Naming Conventionとコメントだけ統一してればいいよ。

649 ：デフォルトの名無しさん：2009/06/16(火) 23:38:52

そもそも、小さなプロジェクトならドキュメントなんて必要ない。