ドキュメントを残さない

普段仕事をしてるとき、いろいろなことに気を使いながら仕事をしてると思う。たとえばissueには、その背景、やりたいことや期待する効果、制限事項、認識している副作用やリスクの情報等などを書くような運用ルールを作っているチームは多いらしい。しかし、私たちのチームではそういうルールはない。それでうまくいくんだっけっていう話をよく質問されるので、考えてみた。

コードの品質をカバーするためのコメント

私たちは、常にわかりやすいコードを書けるとは限らない。解説として、コメントが役立つ場面はある。

ちょっと待ってよ「よし、Why notを書こう！」と言って上手く書けるのは、そうとうに経験を積んだ人だ。そして、経験を積んだ人は大体問題ない。悪いコードほどコメントが必要だが、良いコメントが書けるくらいならコードはもっと良くなってる。鶏と卵じゃん。

コメントについて議論する暇があったら、コードについて議論したほうが有意義じゃない？

歴史は積み重なる

何か新規機能を追加したい。もしくは不具合っぽい挙動を修正したい。そのときに、影響範囲の調査としてissueやコミットログに頼る開発スタイルをしているとしよう。では、5年経ったときに参照しなければいけない情報はどれだけだろうか？

1年経った時の5倍で済めばまだいい。幸いにも事業が上手く進むと、チーム規模は当時の2倍になり、コンテキストの増加ペースは2倍になる。いや、2倍で済むのは相当理想的に整理されている場合で、現場はもっと複雑だ。5年分 * 少なくとも2倍の複雑さ = 少なくとも10倍。同じ仕事をするにも最低10倍の調査が必要になる。人はもっと仕事をしやすい環境に移りたくなり、事業は籠城戦になる。事業の継続性のために、歴史を紐解く必要がない状態にしたい。

未来の誰かへの手紙

未来の不特定な誰かに宛てたメッセージって、どれだけのコンテキストを伝える必要があるかが不明なので、ついついリッチにしてしまうんですよね。でも、それらが本当に役に立ってるの？期待する効果があったかを検証したことはある？読み手が知りたい情報を提供できていますか？

設計者だとかコードの作者のドキュメントは明文化されているところはすでにコードから読み取れたり状況的にわかりやすいことが多い。つまり、改めてドキュメントになっていなくても問題ない。本当に知りたいことは、作者が明文化できてないことだ。ストックされたドキュメントを探し、紐解き、読解して、「当時はその辺、あまり何も考えてなかったんですね」っていう経験はあまりにも多い。

考えていないことを明文化しよう！っていうともう大変。認識しない情報を明文化する。そんなことは人類には難しい事が想像できるだろう。

本当に必要なもの: チームのコンテキストをつなぐ手段

ということで、私たちのチームでの解決案は、ストック情報はコードとDBに残った情報を信頼しようということにしている。不具合っぽい挙動があるときは、期待する動作と現状のコード/データを見比べて対応を考えていけばいい。ドキュメントとの差異を調べても、誰も幸せにならない。

大事なのは、その状況における議論と、議論ができる環境だ。コミュニケーションチャネルを開き、コードやデータが参照できる。チームメンバー（エンジニアではないヤツらも含む）はそれらを見て、次の状況を考えて実現していく。

具体的には、大まかなシステム構成についてコンテキストをつなぐためには、各位がホワイトボードで説明できるような状態を維持すればいい。図をpushする必要はない。