「ドキュメントやコメントを書く」のモチベーションについて
新しいコードとコンタクトするたびに思うこと
会社でコードを触っていると、「そのコードは何をしようとしているのか」とか「このコードが解決しようとしていることはどんな背景があったのか」とかが気になるときがある
コードをじっくり読めばその処理でどんなことをやろうとしているのかはわかるが、結局当時の背景とかコードに落とし込む前に本当にやりたいと思っていたことについてはだんだん忘れ去られて分からなくなってくる
そんな中、コードも書きながらできるだけコメントやドキュメントやコメントを残すことについて、会社の人からドキュメントやコメントを残そうとするモチベーションについて話をする機会があったため、その時に話していたことともうちょっと言語化した個人的な意見について書き残す
※ 内容に重複があるものの、どんなことがあったのかについてまとめる
当時の状況を残し、前に前進するためにドキュメントやコメントを書く
ドキュメントやコメントを書くときのモチベーションはそれぞれあるが、会社と個人開発のそれぞれにおいては以下のようなモチベーションで書いている
- 会社
- 自分が書いたコードが「どんな背景で書いたもの」で「どんなことをしようとしているのか」を、次に触る人が修正する際に判断材料として使ってもらうために残す
- 個人開発
- 未来の自分が過去の出来事やそうせざるを得なかった理由を忘れないために残す
要は、書き捨てではなく 継続してそのプロジェクトが続けられるために書いている ことが主な理由だ
では、「継続してそのプロジェクトが続けられるために」という部分にはどんなことがあるのかと言うと、以下のようなことを想定している
未来のコード修正時に遅延評価されることを前提に書く
後々のコード修正で困らないためにドキュメントやコメントを書く前提として、 今評価されなくてもいい と割り切っている
ドキュメントやコメントがない場合に困ること
ドキュメントやコメントを書いている時点でできているコードは、その時の自分やチームの中で情報として一番新鮮な状態で共有されていてPRのレビューをした際に「そういう意図で書いたんだね」という背景も一番理解している
しかし、その時が過ぎて他のタスクをこなしているうちに「当時は理解していたはずの情報」はだんだん薄れていく
その結果、後になってそのコードを触ろうとするとすると「なんでこのように書かないといけなかったっけ？」とか「こうしないといけない理由ってなんでだっけ？」という状況が発生する
そうなるとコードを書くメンバーが（実際にそういう行動を取るかどうかは置いといて）、 コード修正による仕様やUXの変化について心理的に消極的になり、現状踏襲をしたまま機能開発・改善をしようとするスタンスになる
ドキュメントやコメントがある場合にできること
そこでもし、コード修正をする際にドキュメントやコメントがあった場合、以下の状況を作り出す可能性が生まれる
- どんなことを期待して書いたのかという背景や当時の状況が書かれているので、 コード修正をした場合に生まれる懸念点としてどんなことがあるのか という推測が立てやすくなる
- 予想をもとに仕様の変化の合意とか修正内容のスコープの調整をするための土台となるため、 企画やPMと仕様の理解をすり合わせながら相談する ことができる
- どう実装すればいいのかについてエンジニア一人だけで悩むより、他のエンジニアと 実装方法について雑な相談をする形でコミュニケーションを取るきっかけ となる
このようなことが未来に起きるだろうと想定しながら未来のための資産を残す想定でドキュメントやコメントを残すモチベーションとしている
主要メンバーがいなくなってもプロジェクトを動かすために書く
チーム開発で後々困らないためにドキュメントやコメントを書く前提として、 今のコードを触っている人が永遠にメンテナンスし続けるとは限らない と考えている
ドキュメントやコメントがない場合に困ること
あまり考えたくはないが、今コードを触っている人が退職・別プロジェクトへのアサインなどによってそのプロジェクトから離れるケースもあり得る
そうなった場合、それまでプロジェクトのコードや周辺技術について理解していた人の知識とノウハウに頼れなくなるので、プロジェクトに残る人たちは急に戦力が落ちたまま開発と改善をし続けることになる
さらに、他の人へ引き継ぎをするための時間的な余裕がなく、新たなプロジェクトとかけ持ちをしながら仕事をすることが難しい場合、そのプロジェクトに残る人たちの負担は大きくなる
そして、その人だけが知っていることがドキュメントやコメントに残っていないとノウハウが残らないため、 プロジェクトのチームとしてのパフォーマンスがその時に属している人の能力に依存する 状況が慢性的に発生することになる
ドキュメントやコメントがある場合にできること
そこでもし、人が抜けることになってもドキュメントやコメントがあった場合、以下の状況を作り出す可能性が生まれる
- プロジェクトの設計方針や実装方法などについて 暗黙知のまま共有されることなく、プロジェクトに参加している人が常に参照できる 状態が作り出せる
- よりよい開発方法や方針を提案するための土台として使えるため、過去に誰かが提案した意見という理由で現状踏襲することなく、 プロジェクトに参加しているメンバーの意見や改善案を受け入れられる環境 を整えやすくなる
- プロジェクトを動かすために貯めてきた過去のノウハウや失敗から学んだ経験が蓄積されるので、新規参画者でも既存メンバーでも 学んだことはどんなに些細なことでも共有しようとする意識 がプロジェクトに参加している人たちの中で広まりやすくなる
このようなことがプロジェクトのチームの文化として定着するだろうと想定しながらドキュメントやコメントを残すモチベーションとしている
やりたいことのためにやってきた「失敗」を未来に再検討するために書く
やりきれなかったことがあるの中でドキュメントやコメントを書く前提として、 いま失敗したことが未来のプロジェクトの状況によって活かせるタイミングがくる と信じている
ドキュメントやコメントがない場合に困ること
コードを触っているとパッケージの導入とかチーム全体のための改善につながる活動とかがうまく行かず挫折するときがある
「この方法で試した見たが、うまく行かなかった」ということだけで片付けるとそれ以降はその方法が使えるタイミングや機会が来たとしても「まえに試してみたがうまく行かなかったし、今回はいいや」と諦めたり、アイデアとしてもう一度試そうとしなかったりする
中には、たまたま当時の状況として時間的な余裕がなかったとかパッケージ同士の依存関係が解決できなかったという理由でうまく行かなかっただけなのに、過去の失敗が今でも失敗となると思ってしまうケースが多々ある
もちろん、もう一度試すよりプロジェクトで試してみる価値が高い手段がある場合もあるが、 試せることとして提案する機会が減る という状況が生まれることを助長することになる
ドキュメントやコメントがある場合にできること
そこでもし、一度失敗してもそのときの状況や試したことについてドキュメントやコメントがあった場合、以下の状況を作り出す可能性が生まれる
- 一度試して失敗した方法でも 当時の状況と今の状況を比較して、失敗した方法の中で手順や考え方を変えて試せるものがないか再検討する 機会を作ることができる
- 時間が経って試した本人が思いついた別の考え方とかプロジェクトに新たに入ってきた人の考えとかも取り入れることで 「あのときはできなかったことだけど、今ならできるかもしれない」というポジティブな考え方をするチームづくり に活かせる
このようなことがプロジェクト中で「失敗してもいい」という安心感としてチームメンバーに広まるだろうと想定しながらドキュメントやコメントを残すモチベーションとしている
さいごに
あらためて書いてみると、ドキュメントを残すことは即時性のある方法ではないし、人によってはプロジェクトを動かす上で「守り」の行動として受け取るかもしれないと思った
しかし、プロジェクトの「今」のためにプロダクトの現状を言語化しなかったり、「今」のプロジェクトメンバーだけが分かるコンテキストに委ねたりすると、プロジェクトを継続して作り続けたくてもそれ以上進めることが難しくなる時点が必ず訪れる
そうなる前にチームメンバーの暗黙知・共有すべき知識・失敗したことを言語化することで、時間が経って忘れてしまったり重要なのに共有されなかったりする状況を回避し、チームの資産として残すことができると考えている
ドキュメントを残すことよりコードを書いたり実装したりすることで評価される現場で辛い思いをする人たちが一定数いると思っている
その人たちが、「それでもドキュメントを残すことでプロジェクトの未来のためにドキュメントを書く」というモチベーションに繋げたり維持したりすることを肯定したいと思ったため、今回記事としてまとめてみた
Discussion