第3回　より思慮深いコードレビューを書くためには

フィードバックは私たちにとってソフトウェア本体同様に、個人的にも業務的にも重要です。GitLabではフィードバックのすべてではないにしても、ほとんどのコードレビューを使うことで相互に交換します。コードレビューに関してなら、ツールベルトに追加できるツールをいくつか共有しています。今回は、コード作者とレビュアーのためのコミュニケーション戦略について紹介します。

覚えておくこと：セルフレビューで詳細は重要です

GitLabにおいて、コードの責任はマージリクエスト作者にあります。コード作者はレビューを依頼する前にチェックリストを作成して、細部を確認することをおすすめします。マージリクエストのチェックリストの例を示します。

すべてのフィードバックサイクルの前に：

すべての行を読み返す
コードをローカルでテストする
すべての変更（またはできる限り）のためのテストを書く
マージリクエストに明確な説明を記述し、各フィードバックサイクル後に更新する
変更ごとに少なくとも1つ以上のスクリーンショットを含める（多いほどいい）
ラベルを確認し、再確認する。その後に再び確認する
Monitor：Healthチームが実施しているように、事前にIssueに対して~"workflow::refinement"ラベルを使うことを検討する。チームはラベル機能を使って、Issue、マージリクエスト、エピックに互いに排他的なラベルで注釈を付けることができる。これにより、特定のラベルが一緒に使用されないようにすることで、より複雑なワークフローを実現できる。Scoped labelについてはこちらのドキュメントを参照
レビュアーであるかのようにコードをレビューする。積極的に、出そうな質問に答えておく、フォローアップのIssueを事前に開く
アクションにある最後の最重要な部分を確認するなら、フロントエンド保守のNatalia Tepluhinaの方法を参照する。マージリクエストでレビューアに質問されるであろうことを事前に回答している

誠意を持ちコミュニケーションする

コードレビューを正しく行う上で最も難しいことの1つは、人間味を伝えることです。フィードバックを交換する時、人間の習性として、フィードバックの最も否定的な側面をデフォルトにすることで、認知の歪みを引き出す可能性があります。GitLabでは私たちの価値観に組み込むことで、善意を引き出すことの重要性を強調しています。

従来型のコメントシステムがコードレビューにどのように貢献するか

より効果的なフィードバックを与えるために、従来型コメントシステムを試してみてください。従来型のコメントシステムでは、マージリクエストのレビュー担当者と作者に役立つ方法でコメントを書くように呼びかけています。

従来型コメントシステムはコメントの意図とトーンが分かるように、目を引く一語でコメントを開始するように呼びかけています。この手法により、読者はコメントがどんな立場で発せられているのか理解する機会を得ます。

実験してみましょう。レビューのためにコードをサブミットした時、どちらのコメントを読みたいと思いますか？

例１：代わりに、Xについてどう思いますか？
例２：[suggestion (non-blocking)] 代わりに、Xについてどう思いますか？

恐らく例２を選んだのではないでしょうか。命令や必須の変更としてのコメントではなく、別のアプローチを試すための提案として、コンテキストがあり、共感を持ちコミュニケーションしながら構成されているからです。

このコメントで魔法となるのが冒頭の「suggestion (non-blocking)」です。コメントを読む前に、即座に、以下の最も重要なポイントが分かります。

レビュアーからの提案であること
「non-blocking⁠」⁠、コードの安定性に必要で難しい変更というよりは、親近感をこめた提案であること

こうしたスタイルのコメントのもう１つの利点は、マージリクエストの作者にとって、レビュアーが自分の作業をブロックしていないことを理解できることです。「⁠blocking」と「non-blocking」をハイライトすることで、マージ作者はレビュアーが伝えようとしているコンテキストを完全に理解できます。

例えばマージリクエストをコミットすると、レビューには8つのコメントが返されたとします。例１だと、コメントにコンテキストがありません。すべてのコメントはブロッカーとしてカウントされるものかそうでないものか、そうしたコンテキストがないため同等に扱われます。例２だと、従来のコメントシステムを使用してコメントにコンテキスト化します。コメントを優先順位で扱うことができます。

ブロッカー：ライン上でマージを取得するために必要なもの
非ブロッカー：別途のマージリクエストとなりうるもの、または議論のきっかけとなるもの

今度コードをレビューするときには、従来型コメントアプローチを試してみてください。それによりマージリクエスト作者がレビューに返答する方法にどのように影響するか、レビュアーとなるあなたがレビューを離れる時の感情にも関心を持ってみてください。

コードレビューにおける「公正性」の役割

多くの点でコードレビューとは交渉の一形態であり、交渉の成果として、価値があり高い水準が保たれているコードを選択することにあります。優れたコードレビュアー（および優れた交渉人）であるための中心にあるのは公正性です。実際に公正な公証人であることは、コード作者やコードレビュアーにとって最も有用なツールであることが多いのです。

公正性はGitLabでも「行動を許可するためのガイドライン」において、2回も言及されています。

「信頼できて、頼りになり、公正であり、敬意を払うこと」
「すべての人に公正である方法を模索してください」

公正な作者となるために

多くの点において、公正な作者であることが最も簡単です。いくつかの簡単な、すべきこと、すべきでないことは次の通りです。

すべきこと

スクリーンショットを添えて適切な説明を書くこと（十分に強調したいところです）
レビュアーが提案するときのレビュアーの視点を理解すること
マージの特異な部分に事前に対処すること（誰しもあります）
仕事でコラボレーションすることにオープンであること

すべきでないこと

「マージして」
閉鎖的であったり、提案に反感を持ったりすること
ビルドを実行するために必要な手順を含めないこと（あれば負担が軽減されます）

正直に言えば、マージリクエストの公正な作者になることはとても簡単です。ほんの少しの共感でさえ、とても効果的です。コードのレビュアーが自分の努力が徒労に終わっていると感じている時は特にです。レビュアーはマージを次のレベルに引き上げるための手助けをしていると理解しましょう。

公正なレビュアーとなるために

レビュアーとして公正であることはやや困難が伴います。なぜなら、誰しも「コードはこのように書かれるべきだ」といった意見やバイアスを持つからです。バイアスとは、私たちが何かに直面した時にどのように乗り越えるか、そのための何かです。私たちはそれぞれ独自のスタイルや好み、ソフトウェアがどう書かれるべきかの意見を持っていることから生まれます。

こうしたバイアスはコードレビューで問題を引き起こす可能性があります。他の誰かのコードをレビューするとき、個人的な好みが現れやすいからです。典型的なレビュアーは絶対的なものとして考えていることに反応するかもしれません。そして未解決のコメントが増えていきます。

マージリクエストをレビューして、次のようなことが思い浮かんだ時は要注意です。

「このように書くべきです」
「彼らはなぜこのようにするのか？」
「私ならこのようにするだろう」
「これはあるべき方法ではない」

これらに馴染みがあるとしたら、「⁠すべきだ／しなくてはならない」といった一般的な認知の歪みの犠牲になっている可能性があります。

コード作者がレビュアーと異なるスタイルや方法でコードを書いたからといって、コードが間違っているとは限らないと覚えておくことが重要です。もし「すべき」や「しなくてはならない」という表現を含むレビューコメントを書いていると気づいたら、一歩下がり、その提案が公平なところから生まれているか、バイアスのあるところから生まれているか、考えてみる必要があります。自問してみましょう。ここでは絶対値の使用が保証されているでしょうか。時にはそれが公正で正統なものとなるでしょう。一例として、GitLabが行うような一連のコーディング規則に従っている場合があります。それらの意見が個人的な好みのための薄いベールである時には警戒してください。

意見で「すべき／しなくてはならない」と表現する必要がある場合には、コード作者に変更の必要性を理解できるように、主張の支えとなるドキュメントを必ず添えるようにしてください。

通常、レビュアーが同意できない時の公正な反応というのは、別の方法で行う必要があると主張するのではなく、作者に「なぜこの方法でコードを書いたのか」と訊ねてみることです。