ドキュメントを残さない

普段仕事をしてるとき、いろいろなことに気を使いながら仕事をしてると思う。たとえばissueには、その背景、やりたいことや期待する効果、制限事項、認識している副作用やリスクの情報等などを書くような運用ルールを作っているチームは多いらしい。しかし、私たちのチームではそういうルールはない。それでうまくいくんだっけっていう話をよく質問されるので、考えてみた。 コードの品質をカバーするためのコメント私たちは、常にわかりやすいコードを書けるとは限らない。解説として、コメントが役立つ場面はある。 ちょっと待ってよ「よし、Why notを書こう！」と言って上手く書けるのは、そうとうに経験を積んだ人だ。そして、経験を積んだ人は大体問題ない。悪いコードほどコメントが必要だが、良いコメントが書けるくらいならコードはもっと良くなってる。鶏と卵じゃん。 コメントについて議論する暇があったら、コードについて議論したほ

[masatomo-m]

これ、コアメンバーが抜けるとプロダクトが死ぬ奴なんじゃないかなあ。ちなみに自分はWhy notコメントは数ヶ月後の自分がそのコードを見たときにすぐに設計・実装意図を思い出せるかどうかを基準にしてるかな

[teraph]

サービス終了までずっと同じメンバーで仕事回すつもりならお好きにどうぞ

[laiso]

コードで表現できることは別の形式で残さないということかー（はてなブックマークコメント群は完全に仕様と設計のドキュメントの役割を勘違いしてると思う）

[yetch]

ちょっと込み入った調べ物する時はグチャグチャでもマインドログ残すようにしてる。口語体でウダウダ書いてる

[w1234567]

コード以外の利用者の作業や会社間の繋がりを含めて一つのシステムなんだよ。コードから読み取れないそういう業務的な情報をドキュメントとして残さないor残せない奴を絞首台に送れる法律を作って欲しい

[uva]

人がいなくなったり、新しい人が入ってきた時はどうするんだろう。うちはドキュメントないからコードを読んでねって伝えるのか

[hoge_fuga_bar_baz]

ホワイトボードで説明できるような状態はどうやって引き継ぐんだろう。口頭伝承だろうか。そうだとしたら、それはドキュメント以上に脆いものだと思うんだが

[tick2tack]

「コードがドキュメント」という人はよく居るが、その多くが途中で宗旨替えする印象ある

[jiro68]

小さなシステムならともかく、ある程度の規模のシステムでそれなりの年数使うつもりならドキュメントを残さないという選択肢はない。自分がしたことを覚えていられるという前提も捨てた方が良い。将来の自分への手紙

[katzchang]

これはおそらくつまり、どういうチームで働きたいかの話です。

[rryu]

詳細な仕様はもうコード読んじゃった方が早いし正確なのでドキュメントを残す意味は無いというのは分かる。

[mas-higa]

将来の自分 (他人) の役に立つ Why not なんて書けない…からドキュメント書かないへの飛躍

[sawarabi0130]

詳細設計書はいらないが、概要と、その時の自分しかわからないことは必ず残す。数ヶ月後には自分ですらわからないものになっている。

[gabari]

要求仕様だけは残す。それ以上はケースバイケース

[koheisg]

これがいつも通用するわけではないけど、少人数のチームでは基本的にこういうアンラーニングなやり方に倒して行きましょい。

[n314]

自分もドキュメントゼロだって書こうとしたけどissue もドキュメントのうちなのか。それなら逆に口頭でのやり取りゼロでドキュメント率100%だった。

[efcl]

https://leanpub.com/livingdocumentation あたりにこの辺の話は大体書いてあった気がする。

[vanbraam]

技術力だけではなく倫理の問題."あの時こう言ったよね"を担保する為に記録が必要.その場限りで書き捨てられる図など誰かの都合で容易に捻じ曲げられる.その結果(前回の図で)正しいコードを書いた人が責められる地獄

[unyaa]

この文章からわかることはコード読める人と一緒に仕事ができる環境が広がってそうだという事。 コード読めてコード書けることが大切なのよい。 資料を一切残してはいけないという感じだと窮屈だが、設計書は不要と思

[tbpg]

アーキテクチャやライブラリ選定の意思決定だとか、そういうのも残さないのかな？

[anqmb]

良いコードと意図が特定できるコードは別の概念なので、「Why not」をコードコメントで残すことは割と重要だと思ってるけど

[ilyaletre]

いつもプラクティカルで良いなーとか思う。(捨てるものを考えているんだろうなー)

[bash0C7]

概ね同意で、自分の趣味としては時系列で情報の断片が「残ってた」程度にあればイメージ作りに十分。 御チームにいたのでめちゃ納得できる話。お世話になっております。

[kenichi_odo]

人が変わらないならそれでいいんだけどね。そんなことよりもコードに必要以上にコメント書かれるのが辛い

[ken39arg]

コードコメントは書かないし書きすぎには書きすぎと指摘してる。 経験上、コミットログを一行でわかるように簡潔に書くことが一番良いと感じるのでgit logで歴史的経緯を追えることを心がけてる。

[yantzn]

コード読んでねだけだと厳しいでしょうに...

[laislanopira]

公文書の話か

[irasally]

継続的に関わるメンバーがずっといればうまくいくのかな？人が生き字引。お客さんとのやりとりの背景残してて助かったこと結構あるから（同じ問い合わせが数年後に発生するケース多し）。忘れちゃうから残してる。

[koogawa]

“不具合っぽい挙動があるときは、期待する動作と現状のコード/データを見比べて対応を考えていけばいい” 実際こうなるケース多いよね

[blueeyedpenguin]

保守されないドキュメントを信じると痛い目を見る。

[Magicant]

開発者が十分に多ければ、分からないことは毎回コードを読んで調べればいいって発想も許されるってことかなあ

[tsutsumi154]

わからなくはないが

[otihateten3510]

バグった時や改修時に「何を真とするか」という話で「誰が知るべきか」を意識する必要があるが、コードだけにそれを落とすと「コードが意味として多義的になってる」「一部のプログラマーしか読めない」問題が起こる

[reteria]

コアメンバーが辞めるときは プロダクトを辞めるとき、みたいな考え方がどっかにあった気もするな

[hnt4]

短期間、例えば2年で死ぬ（ゲーム？）なサービスならスピード重視でそれでも良い。ただ、ヒットして想定外に大規模＆長寿になったりするので、その場合将来大人数で介護する羽目になる。そしてその時貴方は居ない。

[khtno73]

最終的にはコードなんてな当たり前。自社プロダクトが少なきゃこれでOK。プロダクトが多い、SIerでお客向けの製品なら、他者が追加開発やトラブルシュートすんだから統一フォーマットのドキュメントが無いと効率悪い。