心がけている PR の書き方とコードレビューについて
私が普段心がけている PR の書き方やコードレビューの方法をご紹介しようと思います。
そもそもコードレビューってどうやるの、どういった観点でコードレビューをするのか、みたいなところは、わかりやすい記事がたくさんあるので、そちらを参照していだくと良いと思います。
この記事では、 PR の書き方やレビュアーにアサインされた際のコメントの仕方などをご紹介できればと思います。
1. PR を作成する
Github に限定した PR の出し方を順を追って説明します。
下記の画像は PR を作成する際の例です。
ご参考までに。
(1) ブランチの設定をする
派生元のブランチと変更ブランチを正しく設定します。
(2) 説明を記入する
フォーマットが決まっていればそれに従うようにします。
特に決まっていなければ、 Why , What を書くと良いと思います。
- Why
- なぜこの PR が必要なのかを記載します
- PR を出すからにはなにか背景があるはずです
- issue があればそのリンクも貼っておくと、レビュアーや後でその PR を見た人が仕様を把握するのに役立ちます
- What
- どんな変更をするのかの概要を書きます
- 画面の変更もあれば、 before / after のスクショもあると良いです
(3) Assignees を設定する
PR のこちらの部分です。
自分を設定します。
複数名いる場合はその人も含めておくと良いです。
これをしないと、あとから自分が担当した PR が探しにくくなります。
(4) submit
全て書き終わったら file の diff をざっと確認し、問題なさそうであれば作成ボタンを押して PR を作成する。
2. PR 作成後にすること
作成した PR をそのままレビューに出しても良いですが、必要であれば下記をやったほうが良いです。
(1) コードにコメントを記入する
見ただけでは分からなそうなところにはコメントを入れたほうがレビューしやすいです。
実装して迷ったところなどは積極的にコメントしておくと良いです。
コメントの仕方ですが、コメントを入れたい箇所のプラスマークをクリックします。
そうするとコメントを入力するフィールドが出てくるので、コメントを書いていきます。
単にコメント書く以外にも色々できますので、 Write -> Preview を繰り返して試してみると良いです。
コメントの submit には、2 通りあります。
Add single comment ボタンは、押すとすぐに反映されます。
Start Review ボタンは、複数のコメントをためて、1 つのレビューとすることができます。
基本的には Start Review の方を使うと良いと思います。
最近、コメントに動画をアップロードできるようになりましたね！
手元で gif に変換しなくて良くなったので、とても助かっています。
cf. https://github.blog/changelog/2020-12-16-video-upload-public-beta/
実際に動く画面を見せられると、レビュアーはとても安心します。
(2) レビュー依頼を出す
コメントもし終わったらレビューに出しましょう！
レビューお願いします！だけでなく、どんな PR なのかも添えて依頼するとレビュアーは嬉しいと思います。
下記のように一言添えるだけで結構違うはずです。
xx のため、 oo を変更する必要が出てきました！
レビューお願いします！
その後 PR の Reviewers にレビュアーを設定してレビュー依頼完了です！
3. コードレビュー
どういった観点でレビューするかは、下記の記事をよく参考にさせてもらっています。
余談ですが、「！」をつけるとトゲがなくなるので私は結構使います。
これはコードレビューに限らず、普段のテキストコミュニケーションでもそうするようにしています。
ビジネスびっくりです。
更に余談ですが、 :thinking_face: , :man-bowing , :pray: の絵文字はかなり使います。
これつけとけばなんとかなります。
下記は同じ文章ですが受ける印象はだいぶ違うと思いますがいかがでしょうか？
- xx したほうが良いと思います
- xx したほうが良いと思います。
- xx したほうが良いと思います！
話がそれました。
また、コメントの略語を使っても良いと思います。
前職の同僚から教えていただいた記事ですが、私はこちらの方法を使っています。
こんなかんじでラベルが打てます。
少し華やかになりますでしょう？
ちなみに URL 変えれば色々できますね。
| url | badge |
|---|---|
https://img.shields.io/badge/Hello-world-purple.svg |
 |
レビューして、問題なさそうであれば、 Approve して LGTM しましょう！
さらに一言添えると気持ち良いと思います。
LGTM です！！
実装ありがとうございます！お疲れさまでした！
4. レビュー戻りがあった場合
レビュー戻りがあったら対応しましょう。
可能であれば 1 指摘 1 commit にすると良いと思います。
そうすることで、返しのコメントで下記のように書けます。
レビュアーも該当コミットだけ確認すれば良くなります。
xx するように対応しました！ <commitのリンク>
一通り修正して返し終わったら Reviews の Status をクリックして黄色の丸に変更します。
これをしないと、レビューアーが下記 URL でレビューリクエストされている PR を確認できません。
終わりに
以上、普段心がけている PR の書き方やコードレビューの方法をご紹介しました。
なかなか記事だと伝えにくいなーと、書いてて思いました。
ご参考になれば幸いです。
Discussion