こんにちは、Gaji-Labo アシスタントエンジニアの石垣です。

今回は、自分のアシスタントエンジニアという立場で学んでいる視点から見た、チーム開発をする上で、GitHubでコードを共有する時にしておきたい工夫の第一歩について書いてみます。

弊社横田が以前書きました「レビュアーの視点を想像した伝え方の工夫」と対応する部分もありますので、あわせて読んでいただけたらと思います。

Pull Request を作る = 「提出」ということ

Gaji-Labo には GitHub でのレビュー文化があります。レビューを通さないでマージされるPRは基本的にはありません。

そのため、Pull Request を作ってレビュー依頼をするということは、提出・納品に等しいと考えられます。

まだその考え方が無かった頃、レビュー依頼をした後にPRにコミットを追加してしまったということがありましたが、今では依頼後にコミットを追加することは無く、修正があればその旨をコメントしてからコミットを追加するようになりました。

「提出」するにあたって大事なこと

提出する、ということは、自分の作業を他の人（レビュアー、他作業者）に手渡す、ということです。

そのためには、作業内容を分かりやすく、そして確実に伝わるようにするのが最も大切なことだと分かってきました。

それを意識すると、PR上で出来る工夫はいくつも見えてきます。

コメントをしてからコミットを積む、他の人に分かるようにPRを工夫する、というのは当たり前のことかもしれませんが、チーム開発に不慣れな人にとって何も分からない状態でそれを行うのは難しいこともあると思っています。

これから、コード共有する際に必ずやっておきたい実作業について、「チーム開発で何が大切なのか」というのを学んできた観点で書いていきたいと思います。

コード共有する際に必ずやっておきたいこと

全 Commit と Files Changedを必ずチェックする

これはそもそもミスを漏らさないことに直接的に繋がるので必須でやっておくべきことです。

しかし、この工程はミスをチェックするだけではなく、「このPRは求められる作業内容に沿っているか？」「このPRはレビュアーが把握しやすい量と内容になっているか？」ということを考えるプロセスにもなっています。

レビューされる前に、前もって自分でレビューを行うイメージです。

レビュアーと同じ目線で同じプロセスを踏むことによって、PRの内容を客観視することができ、レビューされるにあたって必要なところ・足りないところも見えてきます。

作業内容が分かりやすく伝わるように description を書く

description は、PRの内容を伝える上で最も有効的で大切な箇所です。

ここで気をつけたいのは、全てを説明するだけがわかりやすい description ではないということです。

PRの見せ方に気を配り始めた頃、作業内容の全てを description で説明しようとして「逆に分かりづらくなっている」というアドバイスを貰ったことがあります。

その時、「全てを説明するのではなく、そのPRの内容を最も分かりやすく伝えられるのが良い description」ということを教わりました。

たとえば、CSSの修正で見た目に差分が発生する作業の場合、見た目の違いを言葉で説明するよりも差分のキャプチャを一つ貼る方が分かりやすいと思います。

見た目には分からない修正でも、細かい書き方の違いではありますが「AからBに変更した」と書くより「A => B」と書くことで、擬似的な差分のキャプチャのように前と後が明示的に分かりやすくなるということもありました。

プレビューリンクがある時はリンクを貼るなど、最も分かりやすく適切に伝えられる方法は何かを考えることが大事です。

また、Files Changed と同じように、書いた後に客観的に見返すのも大切なことです。

desciption に必要な情報を全て明記する

description に元となる issue の番号を書く

作業にはその文脈があることが多いです。

元となる issue の番号をref: #00のように明示しておくのも他の人に作業内容を共有するために必要なことです。

description で依存関係やマージ順序の指定を伝える

PRによっては、マージする順序が重要なものがあります。そういったPRがある時は、必ず description に依存関係を明記しておきます。

これらは自己完結せず、他の人に作業内容を共有するという観点で考えると必ずやっておきたいことだと理解できると思います。

まとめ

• 全 Commit と Files Changedを必ずチェックする => ミスを無くし、作業の内容と粒度が適切かを見直す
• 作業内容が分かりやすく伝わるように description を書く => 全てを説明するのではなく、PRの内容を最も分かりやすく伝える
• desciption に必要な情報を全て明記する => 自分の作業と、それに何が必要かを全て把握し、それを他の人にも不足なく伝える

まだまだ工夫できることは大量にありますが、第一歩である3点について書いてみました。

上で書いていることの全ては、自己完結せず他の人に作業内容を共有するためという視点に基づいて行っていることです。

何のためにPull Requestがあるのかを常に忘れないことで、レビュアーや他作業者にとって分かりやすいPRを作成することが出来ます。

これらはこの2年の間に学んだことで、実案件に関わっているなかで確実に身についていると感じています。

自分のような駆け出しのエンジニア、特にチーム開発で悩んでいる人の参考にしていただけたらとても嬉しいです。

Gaji-Laboブログ内には、他にもフロントエンドがパートナーと協業するときの工夫について取り上げた記事があります。
フロントエンド領域のスムーズな協業とコミュニケーションの向上に関心がある方におすすめの記事シリーズを「フロントエンドがパートナーと協業するときの工夫」としてまとめていますので、あわせてお読みいただけるとうれしいです。