よくコミュニケーションの研修などで、
“「どう伝えたか」より「どう伝わったか」が大切なんだ！”
って言われますよね。
逆に言えば、
“どんなに熱心に伝えても、伝わっていなければ意味がない”
ということになります。
これをプログラマ的に置き換えてみましょう！
“どんなに完璧な設計書でも、読み手(作り手)次第で不出来になる！”
……そんな経験ありませんか？
一方通行だから祖語が出る
コミュニケーションは互いに意思伝達をしなくては成り立ちません。
例えば、貴方が（自分の中では）完璧な設計書を作ったとしましょう。
実装者に「設計書通りに作れば大丈夫だから！」と丸投げすると、
大抵想像したものと異なるものが出来上がります。
最悪なケースだと
「いっぱい」の1文字目の「い」を「お」に変えてください。
という単純な指示ですら
「おっぱお」
と返ってくることがあります。
当然どうしてこうなった？となるわけですが、
『い』を『お』に変えろって指示だったので…
ちゃんと文章を読みましょう。
横展開で最後の『い』も『お』に変えておきました！
笑顔で言われても苦笑いしかできません。
これが会社の同僚など近しい間柄なら笑い話で済みますが、
顧客やお金が絡んでくると大問題です。
作業者からレビュワーに伝えることが大切
話をタイトルまで戻しましょう。
「伝わったことを伝えるプルリクを出そう！」とはどういうことか。
簡単な話です。
作業者が「自分はこの設計書をこう読み解きました」を記入すれば良いのです。
例えプロジェクトルールが『プルリクのコメントは設計書や課題管理のURLなどを貼り付けておけば良い』だったとしても書いてみましょう。
だって 設計書はおっぱお なんだから。
難しく考えなくても、大体以下のシンプルなテンプレートで事足ります。
機能実装時
## 修正内容を一文にまとめる
- 設計書を確認しながらひとつずつ
- 処理の流れを意識しながら順番に
- やったことを列挙していく(コピペ厳禁)
#### 動作確認
- [x] 上記を確認しながら（動作確認しつつ）列挙する
- [ ] 後で確認することも記載しておく
実際にGitHubで書くとこんな感じになります。
バグ修正時
## バグの内容を一文にまとめる
#### 原因
- 直接的な原因
- 間接的な原因
- どのような経緯で発生したのか
#### 対応方針
- 〇〇という理由から（←重要）以下の修正をおこなった
- ここも Files changed 等を見ながら
- やったことを列挙していく
#### 動作確認
- [x] 上記を確認しながら（動作確認しつつ）列挙する
- [ ] 後で確認することも記載しておく
「こういう点を考慮して、このような処理にしました」といった理由は、ぜひ残すようにして欲しいですね。
誰が助かるのか
こんなの時間の無駄じゃないか！と思う方もいるでしょう。
『おっぱお』になった原因をヒアリングする方がよっぽど無駄だよ！
さて、こんなことをして、誰が助かるのか。
まず何より、レビュワーが助かります。
大抵作業者よりレビュワーの方が少数で、「レビュー待ち」が発生するほど忙しいです。
このコメントを見るだけで、作業者がちゃんと設計書を読めているか確かめられます。
「やったこと」が少なかったり余分なものがあったりしたら、その時点で目を皿にしてコードを読む必要がなくなります。
（作業漏れがある場合、コードの差分がないのでコードレビューだけでは気付きにくい問題もある）
そして、作業者も助かります。
作業漏れや確認漏れがないか、書きながらちゃんと確認してください。
ここが他人に迷惑をかけない最終ラインです。
さらに、未来の参画者も助かります。
どのような修正をしたのかが一目でわかりますし、Gitなら履歴も探しやすいです。
一番ツラいのが、Historyからバグの原因となる修正のcommit見つけてプルリク表示したら、
仕様書や課題管理のURLが書かれていて、遷移したら参照権限がないパターンですね。
この状態でプルリクのタイトルがブランチ名になってると完全に詰むので、必ずきちんと書きましょう。
誰も救われない結論
伝えたいことは伝わったでしょうか？
「おっぱお」でいっぱいになっていないでしょうか？
爆発時に「爆発オチなんてサイテー！」と鳴るように改修しても良かったと思います。
実は「やること」と「確認したこと」のメモをMarkdownで装飾しただけで、作業者云々は後付けになります。
途中にも書きましたが、コードレビューでは作業者の作業漏れが一番困るので、作業者はひとつずつ「ヨシ！」と指差し確認しましょう。