👨‍💻

コードレビューで気をつけていること

Created
2020/10/12 8:14
Tags
Engineering
Property
チームで働くエンジニアにとって必要不可欠なコードレビュー。
エンジニアリング能力だけが求められるだけでなく、コミュニケーションや仕事の進め方のようなソフトスキルがとても必要だと感じでいます。
下記のエントリーはとても示唆に富む内容で一読の価値があるので未読の方はぜひ目を通してみるかと良いかと思います。
 
一方で、実際にコードレビューする際にはもっと細かいコツなんかもある気がしたので書いてみます。
なお、ここではGitHubを利用していることを前提として、気をつけていることや便利なextensionを紹介していきたいと思います。
 

Reviewer編

コメントの連投を避ける

GitHubのPRコメント欄はスレッドっぽいですが、Slackのようにはいきません。
1つめのコメントを読んでいるうちに2つめが来ても(GitHubの現在の仕様上)画面更新されず、気づかないうちに返信すると文脈が変わってしまうことがあります。
説明されているのにもう一度質問を繰り返してしまっているように見えたり、見返すと容量を得なかったりするのでまとめてコメントしてあげるようにしましょう。

指示語を重ねない

  • ここのコード
  • さきほどの~
  • これとさっきの
など一つ二つなら分からなくもないですが、コメントが長文になってきたりすると読み手側が混乱する要因になりかねないのでしっかりと明記してあげるのが良いなと感じます。

PRを溜めない

1日以内に見てもらえると嬉しいですよね。 Slack連携するだとか1日の最初と最後には見るようにするなど仕組みやルールで解決できるのがベストだと思います。

お勧めツール: github-diff-explorer

とあるコードのレビュー中に別のファイルを参照したいときやdiffが大きくて読みづらいことがありますが、diff-explorerを利用すれば解決する気がします。
個人的に2年近く利用しており、デフォルト設定で見るのはもう無理だと思っています。
 

Author編

PRテンプレートの作成

PULL_REQUEST_TEMPLATE.md を作成するとテンプレートがPR作成時に勝手に挿入されます。
チームでPRの文章構成が統一されているとPR作成のハードルも下がりますのでぜひ。
テンプレートに何を書くべきかはチームによりますが、以下の記事の物など参考になりそうです。
Pull Requestのテンプレートを作って効率よくレビューしよう! | Developers.IO
GitHubではプルリクエスト時のテンプレートを作ることができます。 これによって、プルリクエストに書いてほしいことが明らかになるため、レビューする側も効率よくレビューできると思います。 そこで今回は、私が以前に作成したプルリクエストのテンプレートをご紹介します。 GitHubでは、Pull Requestのテンプレートを作ることができます。 Pull Requestに書いてほしいことが明らかになるため、レビューする側も効率よくレビューできると思います。 このPull Requestでやったことはなにか? このPull Requestでやらないことはなにか? 動作確認は何をしたのか? 特に気になるポイントやちょっとしたモヤはあるか? 個人的に 「やらないことを明記」 は大事だと考えており、レビューする側が「単に忘れてるだけ? それとも後でやるつもりなの?」で迷うことが無くなるのは大きいです。 ただし、Pull Requestの粒度や内容はチームやプロジェクトの特性によってかなり異なると思います。 そこで今回は、私が以前に作成したPull Requestのテンプレートをご紹介します。 .githubフォルダを作成し、その中に PULL_REQUEST_TEMPLATE.md を作成すればOKです。 $ mkdir .github $ touch .github/PULL_REQUEST_TEMPLATE.md PULL_REQUEST_TEMPLATE.md ## チケットへのリンク * https://example.com ## やったこと * このプルリクで何をしたのか? ## やらないこと * このプルリクでやらないことは何か?(あれば。無いなら「無し」でOK) ## できるようになること(ユーザ目線) * 何ができるようになるのか?(あれば。無いなら「無し」でOK) ## できなくなること(ユーザ目線) * 何ができなくなるのか?(あれば。無いなら「無し」でOK) ## 動作確認 * どのような動作確認を行ったのか? 結果はどうか? ## その他 * レビュワーへの参考情報(実装上の懸念点や注意点などあれば記載) レビューする側の効率も良くなりますが、それ以上にレビューされる側のメリットが多いと考えています。例えば下記です。 ユーザー目線の変更点を書く過程で、動作確認の不足に気づく可能性がある やらないことを書く過程で、「そういえばあの変更もいるな......」と気づく可能性がある 作業内容によって合う合わない項目もあるため、全項目を埋める必要はありません。 各チームに合わせたカスタマイズをしてお使いください。この内容は定期的に見直すと良いですね。
 

下書きを活用する

作業前からDraft機能を利用して進捗を見せると良いでしょう。
また、TODOを明記するとReviewerも含めて何が完了していないかもわかりやすいです。
 

お勧めツール: ImgConverter

画像をアップロードすると横幅いっぱいに表示されるようになり、特にスマホのスクショなんかが縦長なので非常に見辛いです。都度、50%表示にしたりするのが面倒な時にはボタン一つで自動で書き換えてくれるので非常に重宝しております。