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

変数名自体を説明にするしかない

システムハンガリアンを止めて、アプリケーションハンガリアンにする。

>>599
> 特にリリース後の修正箇所に対して正確な
> コメントが書かれているソースが本当に少ない。

これはコミットログやChangeLogの役目だろう

> これはコミットログやChangeLogの役目だろう
ソース内のロジックとコメントは分業してるってこと？

ロジックとそのコメント内容が一致してないから
障害対応してるときに頭からソースを読まなければ
ならないってこと。
そして、修正したPGはすでにいないことが多い・・・・

コメントとソースを同じくらい価値があるものだと考えるのはいいが
コメントとソースを同じように扱ってはいけないだろ

そこまでコメントに期待してないよ。
ただ最初にも書いたけど、表題部の
プログラム名や用途、引数説明すら
まともに書いてないソースが多すぎる
からカキコしただけだ

doxyの1.5.6でツリーが文字化けするのって俺だけ？
1.5.5平気なんだけど

４コマ漫画で８００ページの取扱い説明書

>>603
> 特にリリース後の修正箇所に対して正確な
> コメントが書かれているソースが本当に少ない。

これは 「こう修正しました」 っていうコメントのことでしょ？
それはまさにコミットログ等の役割
コードからは読み取れない 「こういう処理です」 っていうのがコメントの役割だと思う

>>608
"「こう修正しました」"は
ソース内の修正(変更)履歴のことを言ってる。

>>609
そりゃあSCMがない時代の苦肉の策でしょ

>>609
バージョン管理使おうぜ

>610,611
今、休出でVSS見てるけど、コミットログやChangeLogは存在しない。
各ソースのチェックインコメントは全部一緒で"○○○○更改に対する修正"・・・・
ほかに見るとこあれば教えてくれ。

（インフラ側で作ってる基盤モジュールのアップデート履歴のほうが
詳細に記載している。）

>>612
履歴を残そうという意識が作業者に無ければコミットログにも残るわけ無いだろ。
お前んとこのローカルな事情だな、それは。

で、一般的に履歴を残すんならどっちかというとコミットログのほうが適切という話。

>>612
コミットログはチェックインコメントと同じ意味
ツールが違うと用語が違う
チェックインコメントが全部一緒だと無意味だと感じませんか？
チェックインコメントは修正内容を記録するのにうってつけだと思いませんか？

ソースに履歴コメントされても探すのが大変だし。同時に変更したファイルの関連や前後関係も把握するのも正確に記載するのも困難。
コミットログならすぐ探し出せる。コメント漏れがあっても差分を見つけられる。
コミットログに情報がないというのは、結局コメントの入れ方、運用の問題でしょ。

ソースが動かないというのは、結局プログラムの書き方、プログラミングの問題でしょ
みたいな感じに見えた

【コメント】doxygen【コンソメ】
http://pc11.2ch.net/test/read.cgi/tech/1212144627/

doxygenの話題は禁止

http://www.hotdocument.net/
じゃだめかな。

これはひどい

doxygen,hotdocument,visio

どれがいいだろうか・・・
C++Builder2007なんだけど。どれ対応してるかもまだ調べてないんだ。

とりあえず・・・探すか。

詳細仕様の中でBNFを使用したら「意味がわからん」と言っておこられましたorz

何か適当な代替え手段はないでしょうか？

# 何年ソフト屋やってんだ？ BNFくらい読めよ > 某メーカの糞 SE

アキバのチョムチョムでやけ酒の飲むしかないね。

知らないと読めないんだから確認しなかったお前が悪い

BNFの書き方が悪かったんじゃないの？

要所で適切な名前をつけて分割してあれば読みやすいし、
BNF知らなくても直感的にわかると思う。
逆に、１行でだらだら書かれたりすると、いくら正しくても読みづらい

学生「意味が分からない．」
先生「意味が分からない．」

構文の説明でもオートマトンで図示するのが多いかな

>>625
条件指定できる設定ファイル用なので、そんなに巨大なツリーじゃない
そもそも, BNF の読み方を知らないらしい

>>627
Pascal の構文定義に使ってある奴？ あれって、けっこう一般的なの？
つか、BNF と変わらないような気もするが…

大量の使用例を書くしかないのか？

BNFじゃなくてSEFで書かないとだめです

理解したいというなら教えてやれば言いと思うけど、単に
xxx *= yyy | xxx yyy
を
項 xxx は、単独の yyy または xxx に続く yyy によって定義されます。
とかの半分機械的な置換で済むかもよ。

>622
BNF云々というより、人との付き合い方の問題な気がする
TPOとか判ってないでしょ
他人のオナニー文書を読まされる側の立場にもなってみろ

>>631
書き手：「お前のオナニー用エロ文書を書かされる立場になってみろ」
読み手：「他人のオナニー文書を読まされる側の立場にもなってみろ」

不毛な・・・

言いたいことがわからない

仕様書はどっかの機関が音頭を取って規格化してほしいわ

フローチャートは全面禁止してほしい

ドキュメントって小説みたいなところがあるよな。
どんなに文字を尽くして書いても、相手の頭にすっと入ってイメージを
作れないと負け。

駄目なドキュメントって、たぶんすべて書いてあるんだろうけど
量ばかり多くてツマラン推理小説みたい。筋の5W1Hがさっぱり見えないで
筋書きを楽しむ以前に何がなんだかわからないオナニーみたいなやつ。

彼氏（彼女）のオナニー見ながらオナニー
見せ合いっこはｺｰﾌﾝする

あるある

俺様要求仕様書と俺様詳細設計書のガチンコ勝負！

質問させてください。
学習目的で小さなプロジェクトを立ち上げようと思っているのですが、
各種ドキュメント（基本設計、詳細設計、テスト仕様書等）の雛形、規格のようなものは
どこかで公開されていないのでしょうか？

IEEEって団体が作ったものがあるようですが
無料ですぐに手に入るものではないようです。

他にどこか有名な団体が作成したものがあるでしょうか。
できれば日本語が好ましいです。
よろしくお願いします m(__)m

俺みたいな底辺SEはプロジェクト終了と同時に傭兵のように各地に派遣されてるから
行く場所場所でドキュメントの定義やスコープ、はたまた名称まで違ってて毎回混乱・・。
その場所のしきたりに慣れるまでストレスを追わにゃぁならん。
プロジェクトの規模にもよるから当然ちゃ当然だが、ドキュメント類は
大まかな指針のようなものに従って書いてもらいたいし、書きたいわけだ。

どこかの学者様かスーパーＳＥ様あたりが統一規格のようなものを打ち出してくれて、
それが広まってくれれば助かるんだがな。

大丈夫、底辺SEがどんなに頑張っても既に採用されている仕様書のフォーマットが変わることはありえないから。
そもそも用語でさえベンダ間で互換性がないんだから、どうしようもないな。

ドキュメントは既存フォーマットを改良して作るのが一番てっとり早いわな。
であるならば、新規プロジェクトを起こす場合、最大公約数的な雛形となるべき指針が
存在してもいいはずだと思わんでもない。
ま、下請けが納品する場合はどうあがいても、大手のフォーマットを利用せざるを得んのだろうが・・。

ちょっと探してみたんだが
ttp://www.hotdocument.net/
↑あたりはなにかしらのフォーマットを利用したんだろうか？

何を持って良いドキュメントって言うんだ？

普通そこらに転がってるドキュメントって、
＊＊＊ このように、できてます！！！ ＊＊＊ が、書いてあるだけで

＊＊＊このように作らなければならない理由＊＊＊ が、書いてない。
＊＊＊もっと上の仕様書との連続性もない＊＊＊ 場合がほとんど。

なので、メンテナンスの役に立たない。

>>640
大手ベンダが専門の標準化チーム作ってフォーマットをガリガリつくってんのが現状。
派遣ソルジャーがデータ持ち出さない限り表にゃあ出てこねえよ。

IPAの発注者ビューガイドラインとかどうでしょう。
発注者視点ですが、開発者でも使えると思う。

これあたりは熟読すればいいんじゃなかろうか？
ttp://www.sage-p.com/process/process.htm
俺めんどくさいから目通してないがｗ

Naming Conventionとコメントだけ統一してればいいよ。

そもそも、小さなプロジェクトならドキュメントなんて必要ない。