プログラマーにドキュメントを書かせるには? 101
ストーリー by reo
結論は至ってシンプルだった… 部門より
結論は至ってシンプルだった… 部門より
cheez 曰く、
本家 /. 記事「How To Get Developers To Document Code」より。
コードのドキュメントがきちんと作成されていない? 問題はプログラマー達にあるのではなく、プロセスにあると Fatal Exception の Neil McAllister 氏は言う (ネタ元) 。
「コードのドキュメントをきちんとまとめる開発者は非常に少ない。ドキュメントを書かせること自体が難題と言ってもいいだろうが、しかし不可能ではない」とのことで、同氏はドキュメントを作成する習慣を確立するためにも「ムチよりもまず飴」方式を採用すべきとだと提案する。多くの人と同じく、プログラマーだって命令よりもインセンティブの方が動機づけとなる。簡単な賞賛も大いに功を奏するが、他の手段を模索するのも良いだろう。彼らが週末にサポート業務で待機担当だったり、またアップデート作業で深夜に作業している時はないだろうか? 追加のドキュメント業務に精を出した彼らにはそういった他業務の負担を軽くしたりするのも一案だ。また、金銭的なインセンティブも有効なのはもちろんである。
/.Jer の経験から見て、プログラマーのドキュメント作成の壁となっているもの、そしてそれを取り除くコツはなんだろうか?
スケジュールの最後に、ドキュメント書く時間をくれ。 (スコア:4, 興味深い)
(一切、邪魔されない) ドキュメント書く工数を入れてくれ。
そもそも開発の途中でドキュメントと合わなくなってしまう現象があるなら
当然工数の最後に「ドキュメント書き直し期間」が含まれてなきゃダメなんじゃないか？
結局、開発工数の中に溶けこまそうと無理させているんじゃないか。
開発止めて、ドキュメント作りなおしてから開発再開ってところもあったけど、１度しか経験がない。
大体「議事録にあったはず・・・」とか「イツイツそういう話が出てきた・・・」とかそんな話になってる。
ついでに。
関係者と話していて、「あ。この話ブレそうだな」とか「相手が協力的な態度じゃないな」と思うと
ドキュメント書くの一気に萎えません？ 私は萎えます。
==========================================
投稿処理前プレビュー確認後書込処理検証処理前反映可否確認処理後……
逆では？ (スコア:1)
最初にちゃんと仕様書を作り、手順まで含めてレビューしておかないから、時間が無くなるんだ。
そもそも、なんでドキュメントが無いのにモノ作りが始まるのだ？
先ずはそこから疑問として提示した方が良い。
>ついでに。
>関係者と話していて、「あ。この話ブレそうだな」とか「相手が協力的な態度じゃないな」と思うと
>ドキュメント書くの一気に萎えません？ 私は萎えます。
私はそういう時こそちゃんと事前にドキュメントの工数を入れ、検印を貰ってからでないと作成
開始しませんが。
そういう客はちゃんと言質を取って置かないと危ないったら無いですから。
＃下手すると「頼んでないからお金は出さない」とか言い出すかもよ？
Re:逆では？ (スコア:1)
＞(#2082129)
私だって怖いですよ。
流石に、仕様書無い状態からってのはアレですが。(経験0と言えないのが嫌だ)
乖離してるのは良くある話です。
>(#2082259)
私が感じるのは、乖離が多いのは内設。 記載不足が多いのは外設。
「あっち参照」「こっち参照」を避けるために、ベターと同じ内容書いて、
直したつもりが記述コピーされていた別のドキュメントも・・・というパターンも割りと経験しているような。
(先日恐ろしいことに、レイアウトが違うだけで内容は同一の内部設計が別ディレクトリの別ファイルで４つ存在していたというケースに遭遇したばかりです）
外設の記載不足は、テストケース作成時に「あれ？」と気づくべきなのですが。
テスト仕様書を充足させてしまって、外設に反映できていないパターンがあるのかないのか。ちと不安です。
----
先日から始まったプロジェクトで、最後の２日間はドキュメント総点検デーと提案してみようかな。
でもそのプロジェクトメンバー。 お客さんもガッチリしてるし。
開発連中もドキュメント喜んで直すから乖離そうそう無いんだよなぁ。 ～_～；
==========================================
投稿処理前プレビュー確認後書込処理検証処理前反映可否確認処理後……
Re:スケジュールの最後に、ドキュメント書く時間をくれ。 (スコア:1)
責任うんぬんとは別ですね。
そういうブレブレになっている場合は、
仕様書や設計書に取り込まれずに、別に作られていたりするんですよ。
そう。「懸念事項確認一覧」とかね。
しかも分かりにくい階層に放り込まれてたり。
それを、すぐにドキュメントに反映させられないのは、何故かって話です。
懸念事項確認一覧なんて表をやめて、BTSに入れとくって人も居るでしょうし
私の場合は、最後に総点検する時間が欲しいと思ってるわけです。
==========================================
投稿処理前プレビュー確認後書込処理検証処理前反映可否確認処理後……
読まれないドキュメント (スコア:3, すばらしい洞察)
>彼らが週末にサポート業務で待機担当だったり、またアップデート作業で
>深夜に作業している時はないだろうか?
>追加のドキュメント業務に精を出した彼らにはそういった他業務の負担を
>軽くしたりするのも一案だ。
経験上、ドキュメントを作成して顧客や別担当者に渡しても読まれない。
全てはそこに書いてあるとしても、ドキュメントを読み漁るよりも
携帯電話一本で済まそうとする人間が多すぎるのが根本的な問題なのだ。
プログラマやＳＥに求められるのは、文筆家のような洗練された文章力と
読みやすく校正する編集力、そして興味を引き付けるデザイン力だろうが、
それができるならばプログラマなんかしないで本でも書いて印税暮らし
してるか、出版社でも経営してるはずだ。
メメント (スコア:2)
ドキュメントをちゃんと読む人間は一人は確実にいる. それはドキュメントを書いている私だ.
3日前にコードを書き上げて, そのまま逃亡を企てている「私」というプログラマの首根っこを押さえつけて無理やりにでもドキュメントを書かせる.
何故そのような実装になっているのか?
未記載の制限事項は無いか?
ドキュメントとコードを付き合わせてみれば, コードを書くときに考慮不足だったところも見えてくる. だからドキュメント書きはやめられない.
結果, ドキュメントがコードと同量から数倍にふくれることもしばしばで, 上司から怒られることも.
Re:読まれないドキュメント (スコア:2, すばらしい洞察)
斜に構えて俺カッコイイ発言して酔う前に少し脳味噌使え。ユーザー向けだろうが開発者向けの内部ドキュメントだろうが同じ事だ。
問題になってるのは「俺が書かされるこのドキュメント、本当に読む奴いるの？書いたはいいけど放置されて次に誰かがこのプログラム弄る必要が出る頃にはソースが残ってるかすら怪しい状態で担当者が俺を逆恨みしながら考古学ごっこする羽目になるんじゃねーの？」ってことだ。
少しでも実務経験があれば思い当たるはずなんだけどねぇ。
ドキュメント書く時間くれ (スコア:2)
度重なる仕様変更？
別にかまわんよ。時間くれるなら。
機能追加？
別にかまわんよ。時間くれるなら。
こういうのと似たようなもんですかね。
# 仕様書は書いてるうちにおかしなところを見つけられることも多いし、
# 書いてると考えがまとまってくることも多いので書くようにしてます。
Excelで書かせない (スコア:1)
なんでもかんでもExcelはやめてくれ。
進捗報告は進捗管理システムに記入させてくれ。
バグ報告はバグトラッカーに記入させてくれ。
専用のシステムを使わないことの負担は記入者と管理者(この二つは同一人物のこともある)にのしかかるんだ。
Re:Excelで書かせない (スコア:1)
専用のBTSって本当に使いやすい?
エンドユーザからもマネージャからも管理者からも評判がいいやつには出会ったことがない。
今Excelを使っているなら、もっと使いこなす方向で検討してみたら。
表計算や方眼紙だけにしか使わないのはもったいない。
最初は共有ブックで始めて、ある程度の規模になったらDBを立てて裏で繋ぐようにマクロを組む。これだけ。
Excelのフロントエンド化までできれば、他のフロントエンドの種類も好きに増やしていけるよ。
Re: (スコア:0)
Re:Excelで書かせない (スコア:1)
そうそう。しかもそのドライバー使い、穴をあけるのも直線引くのもドライバーで済ませようとしがち。緊急避難・応急措置ならいいんですが、なぜか公式の手順にしてしまおうとする。
Re:Excelで書かせない (スコア:1)
1) DocBookでも何でもいいから、テキスト型のマークアップ言語で書く
2) それを Excel に張り付けるスクリプトを書く (VBA で書いてもいいし、Perl + Spreadsheet::WriteExcel でやってもいい)
ちなみに私はPerl派 ( Windows を立ちあげずに Excel 化できるから )
プログラマたるものが、「Excelで書く」なんぞという問題をプログラムで解決しようとしない、などというのはあり得ない。
なので、Excelは真の問題ではない。
fjの教祖様
Re:Excelで書かせない (スコア:1)
なんでもExcelなんでもExcelで方眼紙という人に話を聞いてみると、
フリースタイルのデジタルドキュメントを書ける方法をExcel以外に知らない
というのが多いような気がするので
OneNote(とこれを動かすのに十分なマシン(現代的なWIndows7マシンならなんでも大丈夫だろう))と
安い小さいのでいいから占有できるタブレットとイメージスキャナを与えるのがいいのではなかろうか。
でもこれだとバグトラックシステムを使わせるという目的にはあんまり適合しないな
Re:Excelで書かせない (スコア:2, 興味深い)
マネージャはExcelしか使えないバカだという前提を除いて考えてみると、マネージャ側が使いやすいと思えるツール類が提供できないからではないのかな。
例えばBTSを動作させるサーバは、誰が準備してだれが運用するのか。
つまり 動的に変化する案件毎に関係者が(機能的にも・セキュリティ的にも)正しく使えることを担保するために、費用がいくら掛かるのか。システム外にいる人と情報共有するために、どれだけ手間がかかるのか。
とか考えると、あながち馬鹿にしたもんでもないと思うんだな。
(自分はExcelは嫌い派だけど)
ドキュメントはユニバーサルなマークアップで書いて、Excelなり任意のプロジェクト管理ツールなりに変換できてしかるべきでは。プログラマなら。
Re:いっそのことすべてExcelにしてみる (スコア:1)
僕たちプログラマーは、プログラミングに、Excelを使います！ - m2 [hatena.ne.jp]
だれが読むのかを明確にする (スコア:1)
ドキュメントの質の基準を明確にする
基準に基づいて評価する
評価にインセンティブを与える
Re:だれが読むのかを明確にする (スコア:1)
読み手のレベルが確定しないと書けないってのはありますね。
こっちにとって当たり前のキーワードが不明だと質問されても
それぐらい常識だろ、としか返せない。
あとこっちもシステム全体の仕様のサブセットをコーディングしているだけなのに、
そもそものシステムの思想なぞ求められても困ります。
私は、未来の自分宛の読み物として書くことが多いですね。
全体の把握のための概論と、あとはおおむね苦労話を「読み物」として。
細かい動作はコードを見ろという方針、現在の自分がひっかっかった所は
未来の自分もまたひっかかるだろうと予想して。
後はもうＦＡＱにしちゃう。誰か読んでくれて、質問来たらまずはそれに答え、
それをそのままＦＡＱに追加。
話は変わりますが、ソースコードを開いた先頭に、「このソースは何をする
（つもりの）ものである」と一行でいいから書いてくれんかなぁ。追いかける時の
安心度が違うのよ。
ファイル名から類推できないからソースを開いて、ライセンスばーっとあって、
部品レベルの関数が続くと読み始めの場所を探すだけで疲れる。
Re:だれが読むのかを明確にする (スコア:1)
話は変わりますが、ソースコードを開いた先頭に、「このソースは何をする
（つもりの）ものである」と一行でいいから書いてくれんかなぁ。追いかける時の
安心度が違うのよ。
ライセンス込みでコピペして修正し忘れそうだけど。
コードしかメンテせずに、知っててコメントを古いまま放置するやつもいる。
「何をする」つもりで作り始めたけど、作っているうちにもっといい方法を思いついたので方針を転換した
→ 初期のコメントは放置
なんてのもある。
全部おれのコードだ。
テスト=仕様とする (スコア:1)
プログラム=仕様よりは現実味があると思う。
もちろん人間がプログラムを書くためには自然言語で書かれた仕様書が必要だけど、テストケースにより要求される(またはされない)動作をNormativeにするってことね。
・コードを修正したらテストを通さなければならないことにしておけば、プログラムと仕様の乖離が生じない。
・自然言語の仕様書ではどうしても微妙なケースでの解釈のブレが生じる。それを避けようとするとどんどん仕様書がプログラムそのものみたいになってくる(HTML5の仕様とか読んでみるとわかる)。
最近のW3Cの仕様は、適合ユーザーエージェントが2つ以上存在しないと勧告にまで持っていけないけど、適合性の判断は用意されたテストケースを通せるかどうかで行うことになってるし。ECMA-262 (JavaScript) もテストケースが用意されるようになったね。
書く時間があるなら書きますよ (スコア:1)
書くための時間が無いから書かない。それだけの話でしょ。
PGにドキュメントを書かせたければ、書くだけの時間をきちんと確保する事ですよ。
Re:書く時間があるなら書きますよ (スコア:2, おもしろおかしい)
書くための時間が無いから書かない。それだけの話でしょ。
PGにドキュメントを書かせたければ、書くだけの時間をきちんと確保する事ですよ。
いや、時間はあっても書きたくない。
だって、動くソースコードがあるんですよ。
それの解説なんて、書くの面倒じゃないですか。
俺以外が書けばいい。
書く奴が俺に質問してくるくらいなら認める。
それなら読みやすいコードになるだろうし。
Re:書く時間があるなら書きますよ (スコア:1)
何となくこの人のソースコード動かないと思う。
Re:書く時間があるなら書きますよ (スコア:1)
動かないんじゃなくて、暴走するたぐいだと思うな
fjの教祖様
他人に書かせろ (スコア:1)
うむ、私も書きたくない。
だから、手下に書かせた。
日本語が危うい中国人だったが、英語とプログラミングの腕はまともだったんで、何気に正しい風味になってた。
ちなみに、手下が二人居て、腕の良い方に書かせた。
一分ばかし眺めて、問題無さそうだから、そのまま納品した。
でも、それには、8051での数バイトを巡る抗争についての顛末が書かれていない。
//「半分こね」と打ち合わせつつ50バイトちょいに抑えたのに、リンクで20バイトもオーバーするって悪夢も今は昔
-- Buy It When You Found It --
インフラ系のドキュメントも悲惨 (スコア:1)
コードのドキュメントもアレだけど、インフラ系のドキュメントはもっと悲惨な状況。
「え？ドキュメント？そんなのなくてもおまえ把握してるんでしょ？」ってな状況で、
毎回激しいバトルを……。毎回同じ説明を繰り返す日々。
書いたところであなたが読まないのは知ってるけど、いつまでもここにいるわけじゃないし、
誰かに引き継ぐ段になってから書き始めてたらまにあわんのよ。
細かいところで忘れることもあるし。
管理者がドキュメントを書くように言わないようにするには? (スコア:1)
Re:管理者がドキュメントを書くように言わないようにするには? (スコア:1)
それはつまり、君のコードは酷いコードなので、ドキュメントを書いて頭の中を整理しろ、と言われているってことです。
fjの教祖様
Re:管理者がドキュメントを書くように言わないようにするには? (スコア:1)
ドキュメントを書くと混乱するのは、頭の中が混乱している証拠。
あと、Excel は「出力形式」であって、入力ツールではないと思うが？つまり、ドキュメントが.xls 形式か、.xlsx 形式になっていればいいのであって、「Excel をエディタとして使え」という意味では無かろう？
そして、.xlsx形式を操作するライブラリは、いろいろあるのだよ？
fjの教祖様
たけしの挑戦状 (スコア:1)
「攻略本を読んでも解けない（走召糸色木亥火暴）」
ってことですね（南無）
"castigat ridendo mores" "Saxum volutum non obducitur musco"
SQLのドキュメント (スコア:1)
いつも悩む。
・フローチャートじゃ表現できない
・ＤＴＤじゃアバウトすぎる（条件や、ソートまで書けない）
いまのところ、時間がある前提でドキュメントを書こうとすると
以下のようにしている。
・DTDでアバウトなIN/OUTのテーブルを記載
・ER図でテーブル結合の関係を記載
・表で取得データ書式（名前、型、サイズ、意味）
・条件を日本語で記載
・一応SQLのコメントも充実に
１枚で表現できる表現方法はないものか・・。
Re:SQLのドキュメント (スコア:1)
>１枚で表現できる表現方法はないものか・・。
それが結局 SQL そのものだったりする。
＃設計書に SQL がどーんと書いてあんの。
プログラマに書かせるなよ (スコア:1)
プログラマなんてコミュニケーションや言語能力に問題のある奴ばかりなんだから、
プログラマにドキュメントなんか書かせないでほしい。
意味不明なドキュメントを渡されても困るんだよ。
そういう仕事はテクニカルライターにやらせてくれ。
ドキュメント通りに作らしてくれればOK (スコア:1)
変更するならそこで開発一旦終了して別プロジェクトにしてくれ。
それだけでいい。
s/プログラマーに/プログラムに/ (スコア:0)
「ドキュメント・フローチャートから」コードを書くのではなくて、
せめてフローチャートくらいは「コードから」機械作成できるようになっていても
この時代にはおかしくないとおもうけど、アプリ等（GNUとかに）あるのかしら。
バグ取にも便利そうなのだけど
Re:s/プログラマーに/プログラムに/ (スコア:2)
Doxygenでいいじゃないか、
でも、ドキュメントは本来、製造より前に作られるべきものだと思うぞ。自動生成されてメンテナンスされないドキュメンテーションなんてソースコードを劣化させたようなもんだ。
Re: (スコア:0)
ドキュメントに従って作っても大抵は期待通り動かない罠。
ドキュメント→理想の形。
＜＜＜超えられない壁＞＞＞
プログラム→現実。
Re:s/プログラマーに/プログラムに/ (スコア:2)
UMLで自動生成とかJavadocとかありますけど、結局開発当初は使えても、その後仕様変更等で手をくわえた後は、ドキュメントも手直ししなきゃならないことが多いんですよね。結局。
自動生成したドキュメントは図が崩れてたり手直ししなきゃならないですから。
事細かく図を書いたら自動でコードを生成だと図（抽象的なもの）がみずらくなります。
コード＝仕様書という試みもいくつかありますがフローのようなものは無理だし。
まぁ結局、コードと仕様書、更に単体試験仕様書と３つも同じことを違う観点で書かなきゃならないのが心理的にはめんどいのと、昔はたっぷり時間と金をかけさせてもらえたけど、最近は短納期・低報酬ですからね。最低限動くのに必要なもの（コード）以外は疎かになりがちです。例え後から苦労することになっても。目先しか見えてないんです。
Re:s/プログラマーに/プログラムに/ (スコア:1)
その手のツールは腐るほどありますが、当然ながら役に立つレベルのドキュメントは生成されない。
あれはコードはあるけどドキュメントがない状態で、ドキュメントをでっち上げるために使うものです。
納品物件やルールによってフローチャートが必須となってるけど時間はないですよとかいう場合ですか。
Re: (スコア:0)
OSSでは知らないが、プロプライエタリでは存在する。2種類使ったことがあるが、当然チャートの各箱の中身はコードそのものもしくはコードに付けたコメント行の中身になるから、綺麗にコードが書かれていないとバグ取りには逆にやっかいだよ。上流工程が楽になるって事の方が多い。
憶測でコメントしますが (スコア:0)
きちんとドキュメントをまとめることができるプログラマのコードには、
そもそもドキュメントは必要ない、ような気がする。
＃経験則では、ないです。
ドキュメントは、「プログラムが読めない人のためのもの」ではない (スコア:3, 興味深い)
これは間違い。
ドキュメントとコードが２つの異なる事を言っている場合は、最低限でもどちらかが間違っている(下手をすると両方間違っている)。
ドキュメントとコードが同じ事を言っている場合、両方をチェックする事でバグの存在を発見できる確率は飛躍的に高まる(人間は、同じ数学問題でも提示のされ方によって解きやすい場合と解きにくい場合がある)。
このように、ドキュメントは「内容確認」のために使うものなので、省いてよいものではないし、機械生成するべきものでもない。
# 機械生成した場合は、プログラマ自身がそれを声に出して朗読するべきである。
# 大抵、バグが見つかる。
fjの教祖様
Re:憶測でコメントしますが (スコア:2)
きれいなコードなら内部設計書はいらないかもしれないけど、操作説明書の類はいるでしょ？
Re:憶測でコメントしますが (スコア:1)
・外部仕様やデザインポリシーはメモ程度で良いのでドキュメント化しとくべき、後になると自分でも何でこんなことをやったのか目的が理解できなくなることがある。
・プログラムの内部仕様をドキュメント化するのは時間の無駄、そんなものを書く時間があるのならば綺麗な読みやすいコードを書くのに時間をかけた方が何倍もまし。
・読みやすいコードが書けないやつに、ドキュメントを書くなんてそもそも無理。
Re:憶測でコメントしますが (スコア:1)
コードとドキュメントを読んでいって、どちらも読みやすい人と、
どちらも読みにくい人のどちらかしか巡り合ったことのない私は不運でしょうか？
後者に限って、「ドキュメントなんて…」と言うわ、口頭説明も嫌がるわ、だったり。
Re:憶測でコメントしますが (スコア:1)
二度同じことを書かなきゃいけない (スコア:0)
プログラムはドキュメントに書くべき内容を機械に理解できるように書いている（書こうとしている）に過ぎない
Re:二度同じことを書かなきゃいけない (スコア:2)
自分は、まずプログラムのコメント欄で機能説明や使い方を書いてから、それをコードに直す方法で作るから、二度同じ事を書いてるけど説明しやすいプログラムになるというメリットがある。
先にプログラム作ってからだと、説明しにくいモノになる可能性がある。
「二度同じ事」という点は同じでも順序によって大違い。
the.ACount
Re: (スコア:0)
文芸的プログラミングをご所望?
Re:そもそもの疑問 (スコア:2)
そいつが「本当は何を書きたかったのか」を白状させるため。
その後、コードと突き合わせて、「言ってることとやってる事が違うじゃないか」と突っ込む。
大抵、そこにはバグがある。
fjの教祖様