プルリクを気持ちよくレビューしあえるコツあれこれ

GitHub前提です！

順不同です。

コードを提案する

❌

divではなく、spanを使ったほうが良いと思いました！

✅

divではなく、spanを使ったほうが良いと思いました！
+ <div>山田</div>
- <span>山田</span>

文章だけで「ここはこうした方がいい」を説明するより、コードも一緒に提案してあげた方が分かりやすいです。

GitHub上だと、以下のように操作するとコードの提案ができます👇️

GitHubのリンクを貼る時はパーマリンクを使う

❌

https://github.com/prisma/prisma/blob/main/helpers/blaze/map.ts

✅

https://github.com/prisma/prisma/blob/85ecd9ab866f956ad4a249634538d353bd059d8f/helpers/blaze/map.ts

• ❌: mainブランチのリンク
  • mainブランチが変更されるとリンク先の内容も変わる
• ✅️: 特定のコミットに対するリンク
  • どのブランチが変更されようがリンク先の内容は変わらない

あとからプルリクを見返したときに、❌️だと内容が変わってしまいます。なので✅️のようなパーマリンクを使ったほうが良いです。

パーマリンクは、GitHubの行部分にあるハンバーガーメニューからコピーできますし👇️

VScode上からでも、行部分を右クリックで表示されるメニューからコピーできます👇️
▲GitHub Pull Requestsという拡張機能を入れる必要があります

!や絵文字を使う

❌

ありがとうございます。
修正します。

✅

ありがとうございます！
修正します🙏

あたたかい文章にするためです。

絵文字は、IMEの設定で変換できるようにすると楽かもです👇️

レビューを早くする

❌

プルリク作成の8時間後にレビュー

✅

プルリク作成の1時間後にレビュー

レビューは早くしましょう！

あと通知ツールは絶対に入れましょう！！！

たとえばGitifyという通知ツールなら、Windows/Mac/Linuxのすべてに対応しているので、迷った場合はGitifyがオススメかもです。

▲Gitifyを使うと、こんな感じで通知が届く

ルールに従ってコミットメッセージを書く

たとえば、以下などのルールがあります。

• Conventional commits：「コミットの種類と変更内容を書こう」というルール
• gitmoji：「コミットの種類（絵文字）と変更内容を書こう」というルール

たとえば、PrismaのリポジトリはConventional commitsで運用されています👇️

私がいま所属しているプロジェクトでは、コミットの種類だけ先頭に書くような運用になっています👇️

修正したときはコミット名を貼る

❌

修正しました！

✅

以下で修正しました！
fix: タグを変更（div→span）

もらった指摘に対して「修正しました」とだけ伝えても「何を？」となるので、コミットを添えます。

また、コミットを添えるときは「コミットハッシュ」ではなくて「コミット名」を貼るようにします。

コミットハッシュだと以下のデメリットがあるからです。

• どういう修正をしたのかリンクを踏まないと分からない
• forch pushすると履歴を追えなくなる

コミット名は、以下の部分をトリプルクリックすると1発でコピーできます👇️

「何を変更したのか」が分かるプルリク名にする

❌

README.mdを更新

✅

README.mdにアーキテクチャの詳細を追加

1回で複数の引用返信するときは空行をはさむ

❌️

✅️

入れたほうが見やすい場合は、入れたほうが良いかもです。

空行は、スペース入りの改行でつくれます。

プルリクは一言で説明できる粒度にする

❌

title:
Admin画面にいろいろな機能を追加

description:
以下のようにいろいろ追加しました。
- ユーザーを追加できるようにした
- ユーザーの役割を変更できるようにした 

✅

title:
Admin画面でユーザーを追加できる機能を追加

description:
タイトルどおりです！

「タイトルどおりです」みたいに、一言で説明できるのが理想だと思います。

Hide whitespaceでレビュー依頼する

❌️

✅️

Hide whitespaceをONすると、空白（スペースやタブ）の変更行が無視されます。

たとえば、❌️はFlutterのコードですが、ラップしているPaddingを削除しただけなのに差分が大量に生まれています。

こういうとき、Hide whitespaceをONにすると✅️のように差分を減らせます。

なのでこういう場合、レビュー依頼するときに「Hide whitespaceをONにしてレビューしてもらうと分かりやすいです」とコメントすると良いかもです。

▲Hide whitespaceはここからONにできます。もしくはURLの最後に?w=1をつけてもONにできます

スクショや動画を貼る

文章だけだと分かりづらい場合、スクショや動画を貼ります。

プルリクを手動で閉じるときは閉じる理由を書く

❌

理由を書かずに閉じる

✅

理由を書いて閉じる

後から見た人が「なんで閉じたんだろう？」と思うからです。

たとえば、以下のように閉じる理由を書きます👇️

• 実装方針が間違っていたので閉じます
• 別プルリク（#123）を立て直したので閉じます

ApproveするときはLGTM画像を貼る

Approveするときに「LGTM！」のようにコメントするエンジニアは多いと思いますが

「LGTM！」の代わりに、LGTM用の画像を貼るようにするとチームの雰囲気が和むかもしれません👇️

LGTM用の画像を探している方は、👇️の弊サービスがオススメです！

• LGTM画像を投稿・シェアするサービスをエッジな構成で作りました

空行やスペースによるムダな差分をなくす

❌

pushする前に、空行やスペースによるムダな差分がないか確認する

✅

CIで空行やスペースによるムダな差分を許可しないようにする

「不要な改行はないかな？」みたいに手動で探すのは無駄なので、仕組みで防ぐと良いかもです。

必要に応じてコードの中にコメントを書く

❌

<button onClick={() => null}>
  登録
</button>

✅

// TODO: ユーザー登録処理を実装する 👈️
<button onClick={() => null}>
  登録
</button>

必要であれば、コードの中にコメントを書くようにします。

たとえば、以下のような場合に書きます👇️

• 「あとで実装予定だよ」な場合
• 「これ何のコードなんだ？」となりそうな場合
• 「仕方なくこう書いてる」な場合

先頭にTODOやNOTEを付けると分かりやすいかもです。
これをアノテーションコメントと呼びます。

自分の気付きをプルリクでコメントする

自分の気付きを書きます。

たとえば、以下のように「この変更があったってことは今後こうしないとダメかもね」を書いておくと、他のレビュアーも「あ、たしかにそうだね〜」となります👇️

ほかにも、「これはこういう機能です」という単純なコメントでも、それを知らないレビュアーからすると調べる手間が減るので良いかもです👇️

「かもです」って付ける

❌

divではなく、spanを使うべきです。

✅

divではなく、spanを使うべきかもです。

最後に「かもです」と付けると、指摘を柔らかくできるかもです。

ただ毎回付けてたら鬱陶しいと思うので、ほどほどに使うようにすると良いかもです。

CI/CDの速度を上げる

待ってる時間が長いと体験が悪いからです。

たとえば、👇️のような対策をします。

• 並列実行できる処理は、ジョブとして切り分ける
• モノレポツールを導入する（例: Turborepo）
• キャッシュを使う
  • パッケージインストール時（例: npm、pnpm）
  • ビルド時（例: Next.js）
• CI/CDマシンのスペックを上げる

レビューコメントにプレフィックスをつける

❌

divではなく、spanを使ったほうが良いと思いました！

✅

[MUST]
divではなく、spanを使ったほうが良いと思いました！

プレフィックスをつけると、コメントの情報が増えます。

• [MUST]
  • 「絶対に直すべきと思ってるんだなぁ〜」が分かる
• [IMO]
  • 「個人的に思ってることなんだなぁ〜」が分かる

ちなみに、プレフィックスをバッジ画像で表現すると分かりやすいかもです👇️

縦長画像にはimgタグを使う

画像をアップロードすると、自動で以下のようなタグが挿入されます。

![367198380-67c77ba1-0b3e-4aec-b6ad-a10df58b3aa4](https://github.com/user-attachments/assets/2bd11172-25d1-4e6e-bcc4-298cc6c050dd)

ただ、この書き方だと縦長の画像が横幅いっぱいになってしまうので見づらいです👇️

このような場合、以下のようにimgタグを使ってwidthを指定すると👇️

<img src="https://github.com/user-attachments/assets/2bd11172-25d1-4e6e-bcc4-298cc6c050dd" width="250px" />

このように見やすくできます👇️

イシューやプルリクのリンクはタイトルが表示されるようにする

以下のようにリストにした状態で、#123のように書くとタイトル付きのリンクにできます👇️

関連issueは同時に閉じるようにする

以下のようにcloseと先頭につけると、プルリクを閉じると同時にissue（#123）も閉じれます👇️

close以外のワードも使えます。

未完成のプルリクはドラフトにする

ドラフトは「このプルリクはまだ未完成だよ！」を示せる機能です。

以下のメリットがあります。

• 間違ってマージするのを防げる
• 一目で「未完成なんだな」がわかる

プルリクを作成する際に、Draft pull requestを選ぶとドラフトで作成できます👇️

非ドラフト→ドラフトは、以下からできます👇️

ドラフト→非ドラフトは、以下からできます👇️

ドラフトで出して、以下のように実装について質問するのも良いかもです👇️

ただし、ドラフト機能は誰でも使えるわけじゃないので注意です。
（課金 or publicレポジトリじゃないとダメかも）

GitHub独自のMarkdown記法を使う

使うと分かりやすい場合は使います。

たとえば、以下などの記法は割とマイナーな気がするので、知っておくと良いかもです。

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

<details>
<summary>index.js</summary>
```js
console.log("hoge");
```
</details>

GitHub Projectでタスクリストを複数作ってカテゴリ分けする

後続タスクがたくさんある場合、レビュワーからすると「今後どう進めていくんだ？」が分からないかもしれません。

なので、以下みたいにissueの中にタスクリストを作って整理しておきます👇️

こうすると、レビュアーは「今後こうやって進めていくのか〜」がわかります。

プルリクのテンプレをつくる

.github/pull_request_template.mdを作ると、プルリクのテンプレを作れます。

自動割り当てする

以下を自動で割り当てされるようにします。

• Reviewers
• Assignees

手動で設定する手間をなくすためです。

現状、GitHub Actionsを使って設定するしかないかも？です。