コードや Pull Request をコミュニケーションの手段として使ってほしい

レビューなり, 過去の経緯を調べる目的なりでコードや Pull Request (以下 PR) を読むとき, 書かれていてほしいと思う内容が書かれていないことが少なくない. 例えば,

背景や目的
全体的な実装方針 (特に複数の PR で一つの目的が達成される場合)
- これまでやったこと, 今やっていること, この次にやること
実装方法
- 他の方法との比較検討, あえてやらなかったこと, 今はやらないこと
気持ち
- 気になっていること, 迷ったこと, 自信がないこと, わかっていないこと

ということで, こういうのを列挙してなぜ書いてほしいのかをまとめよう...かと思ったけど, 挙げるときりがないし, それぞれは表層的な問題でしかないのでやめた.

では根底に何があるかというと, コードや PR がコミュニケーションとして成り立っているかどうかだと思う. 上に挙げたような個別の要求は, コードや PR を見ることで, 現在または将来の自分・レビュワー・チームメンバーに必要な情報が伝わるようにしてほしい, という一言にまとめられる.

もし情報が十分に伝えられない, コミュニケーションとして成り立っていない場合には, コードや PR を工夫して伝える努力をしておきたい. 方法はいくつかあって,

コード中にコメントを書く
PR の説明で文脈を補完する
コードをリファクタリングして可読性を上げる
テストコードを書く

など. コードの可読性を上げることやテストコードで伝えられる情報は最初に列挙したような内容とはちょっと離れているが, 結局これもコミュニケーションに関する話題としてまとめられるはず.

ということで私の気持ちはタイトル通り「コードや Pull Request をコミュニケーションの手段として使ってほしい」というのに尽きます.

想定問答集

書いていなくても察してほしい

ごく少人数のチームで短期的には可能な場合もあるかもしれませんが, 一般的には難しいですし, 将来のチームメンバーにとっては理解できない可能性が高いです.

書くのが面倒くさい・話せばわかる

フロー情報, 特に音声の場合, 話に加わっているメンバーにしか情報が伝わらないので, 手段としてあまり好ましくありません. また将来のチームメンバーにも同じ内容を伝えるためには, 結局書き残す必要が出てきます.

聞かれたら答える

わざわざ聞く時間や労力はゼロではないですし, 聞こうとした頃にはあなたはもういないかもしれません. また, 聞かれた情報しか残らないので, もし聞かれなかった情報があったら消えてしまいます.

別の場所に書いてある

別の場所に書いてあること自体は良いのですが, 相手に伝わる内容になっていない場合にはコミュニケーションが成立しているとは言えません.

よくある例としては, Issue などへのリンクが貼られているものの, そこでは長大な議論が行われており, 全てに目を通さないと最終的な結論が見えてこないといった場合です. こういった場合は相手に伝わりやすいように端的にまとめてからコードや PR に添えるようにしましょう.

何が必要な情報かわからない

以前にレビューで質問されたことを振り返ってみる
実際に他の人のコードや PR を見て, どういったものが書かれていると嬉しいかを体験してみる
セルフコードレビューしてみる

といった方法で客観的な目線を養いましょう.

書くのが躊躇われる

特に自信がないことやわかっていないことについては, 書くことで自分が無知であると宣言しているように感じられるかもしれません.

一方でこれらが書かれていないことで, 当人にとってもチームにとっても不利益となる可能性があります. 例えば当人は, 自信がない・わからない部分についてアドバイスを受けられる可能性が低くなり, いつまでもわからないままになってしまうかもしれません. またチームにとっては, 客観的には自信がある・わかっていると判断せざるを得ず, 例えば自信がないまま書かれたコードであっても, チームメンバーはそれを間違いのないものだと信じてしまうかもしれません.

ただし, 無知が責められるような環境であれば書かないことも自然な選択です. その場合は環境自体に問題があるので, 上長と相談するなど然るべき対処をしましょう.

特殊技能なのではないか

練習が必要であることは間違いないと思いますが, チームで開発を行う上では避けては通れない技能だと個人的には考えています.

コミュニケーション (笑)

これを言っているのはもう一人の自分で, というのも他人にコミュニケーションが苦手だと規定されて生きてきたので, そんな自分が他人にコミュニケーションがどうとか説教するのはちゃんちゃらおかしいと思ってしまっている. でもこの種類のコミュニケーションに限ってはある程度心得があると思っているので書きました.