はじめに

本記事は ZOZO Advent Calendar 2021 の8日目の記事です。

概要

タイトルの通り、GitHub のPull Request（以下、PR）のコメントを書くときに個人的に気をつけていることを記載した記事です。
チーム内でPRのコメントがわかりやすいと言って頂けたので、調子に乗って社外公開に踏み切りました。
※筆者はフロントエンジニアのため、フロントの実装に関する記載になります。

書いてあること

PRの作成時のコメントで心がけていること

書いていないこと

PRの作成方法や手順

内容

いつも記載している内容は下記の項目です。

上記を記載する上で3点、気をつけていることがあります。

その1：対応内容を知らない人が見てもわかるようにする

PRに記載している「概要」「対応したこと」「対応していないこと」について説明します。

「概要」

実装者以上にレビュアーが対応内容を把握しているケースはあまり多くないと思います。
どういう意図で実装されているかを伝えるため、対応を行う背景、方針などを記載します。画面のデザイン変更であれば、変更箇所をわかりやすくするため、変更前と後の画像を添付します。

例）

「対応したこと」「対応していないこと」

大きなPull Requestよりも細かいPull Request派のため、この項目を追加しております。対応したことは、字のごとく実装した内容を記載します。対応していないことは、別PRに分ける場合はその旨を、事情があって実装をやめたものがあればなぜやめたのか記載しておきます。

その2：レビュアーが困りそうなこと、疑問に思うことを予想して書く

PRに記載している「確認方法」「補足」について説明します。

「確認方法」

画面によっては、認証が必要だったり、特定の手順を踏まないと進めないページがあったりするため、リンクやページの遷移を記載します。

例）PCのZOZOTOWNの登録情報ページに遷移したい場合
トップページ > ヘッダーの「ログイン」を押下 > ログイン情報を入力し、ログイン > ヘッダーのアカウント名様をホバーし、表示されたモーダルの「登録情報」を押下 > 表示

「補足」

既存の実装やブラウザの仕様上など、理想の実装とは異なる実装をすることが多々あります。
背景やなぜ現状の実装になっているのか、を記載しておくと余分なコメントのやりとりが不要になります。

また、補足内容がコードと共に説明した方がわかりやすい場合は、コード部分にあらかじめコメントすることもあります。

その3：省略できるところは省略する

PRに記載している「外部リンク」について説明します。

「外部リンク」

参照しているPRがある場合、すでに仕様書を作成している場合はそのURLを添付し、詳細はこちらをご確認ください、と記載します。
手を抜けるところは手を抜きます。

まとめ

いかがでしたでしょうか？

その1〜3をまとめると、レビュアーや未来の実装者（自分も含む）に思いやりを持って、手を抜けるところは抜いて、必要な情報を記載しようといったところでしょうか。

少しでもお役に立てる部分があれば幸いです。

明日は calorie - Qiita さんの記事です。
明日もお楽しみに✨