ソースコードレビューのコメントの補足説明をChatGPTで作成する

## 3行でまとめると

1. ソースコードレビューで指摘を行う際に「指摘事項を修正するメリット」の説明が抜けて、レビューの往復回数が増えがち
2. 「指摘事項を修正するメリット」の説明文をChatGPTで生成
3. レビュワーの手間を減らしつつ、レビュイーに伝わりやすい、ソースコードレビューになる

## 仕事でソースコードレビューするときの話

仕事でソフトウェアを開発するとき、GitHubのプルリクエストを使ってソースコードレビューを行うことがあります。
次の2つの役割の人物が登場します。

- レビュイー：プルリクエストの作成者。レビュー依頼者
- レビュワー：プルリクエストを見て、ソースコードの問題点を発見し指摘する人

### 修正箇所を全部指摘しないと直してもらえない

ソースコードレビューでは、しばしば、つぎのようなすれ違いが起きます。

- レビュイー「この指摘、関数Bにも似てる箇所あるぞ。こっちは指摘されてないな？直した方が良いのかな？直さない方がよいのかな？判断できないし、直さないでおこう。必要があれば、指摘してくるはず。再レビュー依頼しよ」
- レビュワー「隣の関数でも同じなんだからこっちも直してよ。一個指摘したからわかるでしょ。伝わらないならしょうがない。『こっちも直してね』と」

ソースコードレビューでレビュワーが意図した内容が、レビュイーに伝わっていません。
そのため、レビュワーからの指摘と、レビュイーの修正が、何往復かする必要があります。
できれば、お互い一往復で済ませたいですよね。

### ソースコードレビューのふたつの目的

今回はソースコードレビューにはふたつの目的があると考えます。

1. ソースコード上の問題点を発見、修正する
2. レビュワーからレビュイーへ、ソフトウェア開発知識の共有

他にも、「レビュイーの得た実装上の知見をレビュワーに共有する」などの目的も考えられます。今回は扱いません。


#### ソースコード上の問題点を発見、修正する

第一の目的はソースコードの保守性を一定以上に高め、バグの混入を防ぐために行います。
このためレビュイーはソースコードに対して次の項目を指摘します。

1. 修正箇所
1. 修正方法

#### レビュワーからレビュイーへ、ソフトウェア開発知識の共有

第二の目的は、レビュイーが指摘された以外の類似の箇所を自力で発見し修正できるようになることを目指します。

このためには、レビュワーは前述の修正箇所を指摘すると同時に「指摘事項を修正するメリット」を示すべきです。
レビュイーが「指摘事項を修正するメリット」を理解できれば、指摘された箇所以外の類似の箇所を修正するべきかどうか自力で判断できるになります。

前述のエピソードでは、第二の目的が上手く達成できていません。


### ソースコードレビューで示すべき3つ

まとめると、ソースコードレビューでは次の3つの点を示す必要があります。

1. 修正箇所
1. 修正方法
1. 指摘事項を修正するメリット




### 「指摘事項を修正するメリット」の説明が抜けがち

ソースコードレビューでは、前述の3点のうち

1. 修正箇所
1. 修正方法

までしか示されないことがあります。

このとき、第一の目的を満たしソースコードの品質を保てます。
しかし、第二の目的「レビュワーからレビュイーへ、ソフトウェア開発知識の共有」を満たすことはできません。

その結果、レビュイーは指摘された内容だけを修正します。
前述のエピソードのような「修正箇所を全部指摘しないと直してもらえない」が起きます。

では、なぜレビュワーは「指摘事項を修正するメリット」を説明しないのでしょうか？

## 原因はレビュワーの時間が足りないこと

原因の一つに「レビュワーの時間が足りないこと」が考えられます。

### ソースコードレビューに時間が掛かる

ソースコードレビューには時間が掛かります。
ソースコードレビューでは、プルリクエストの目的の次の点を確認します。

1. 目的。主に実現したい機能
1. 実装が目的を満たしているか
1. 実装の設計が適切か。過剰あるいは過小ではないか
1. 命名が適切か
1. コーディングスタイルが適切か。主にリンタ、フォーマッターでチェック出来ない部分

これらの点をみるために、初回のソースコードレビューでは1～2時間掛かることがあります。
ソースコードレビュー中はレビュイーの作業は中断されます。
この時間が1～2時間になるとインパクトが大きいです。


### レビュワーが少人数に集中する

開発チームの中でレビュワーになるスキルを持っている人は少数であることが多いです。
一般的に、レビュワーレビュイーより少ないです。

レビュワーは、複数のレビュイーからのレビュー依頼を同時に受け取リます。
二人のレビュイーから同時に依頼を受けると、ソースコードレビューは合計で4時間掛かるかもしれません。
2番目のレビュイーの作業は4時間止まります。

これが4人になると、8時間、ほぼ一日になるかもしれません。

### レビュー待ち時間を減らすには？

レビュイーの待ち時間は非効率なのでなるべく短くしたいです。
次のような工夫が考えられます。

***「レビュー指摘を修正するメリット」の説明文作成時間を減らし、レビュイーの待ち時間を減らす***

これはソースコードレビューの目的の2番目を諦めることに相当します。
ソースコードの品質を保ちつつ時間を稼ぐトレードオフです。

その結果は、レビュワーは「指摘事項を修正するメリット」を説明しないのであり。
「修正箇所を全部指摘しないと直してもらえない」です。


### その他の工夫

他にも次のような工夫も考えられます。

- レビュワーを増やす
- レビュイーの待ち時間の作業を用意する
- プルリクエストのサイズを小さくする

しかし、レビュワーを増やしてもひとつソースコードレビューの時間は1～2時間から速くなることはありません。
レビュイーの待ち時間の作業を用意すると、レビュイーにマルチタスキングを強要します。
プルリクエストができた後に、小さくするのはそれなりに難しいです。小さくなる予定のプルリクエストを実装してみたら大きな変更が必要だとわかることもあります。

いずれもも根本的な解決にはなりません。



## 「指摘事項を修正するメリット」の説明をChatGPTで生成してレビュワーの時間を節約する

レビュイーの待ち時間を減らすためには、ソースコードレビューそのものの時間を短くしたいです。
ソースコードレビューのうち指摘箇所の発見をChatGPTに任せるのは、現時点では不安が残ります。
ChatGPTはプロジェクト特有のバックグラウンドを知らないので、プロジェクト特有の重要な注意点を見逃す可能性があります。

一方で「指摘事項を修正するメリット」の説明は、ソフトウェア開発の一般論であることが多いです。
ChatGPTは一般論の説明にはすこぶる強いです。
ここにChatGPTを使います。
ChatGPTを使って「指摘事項を修正するメリット」メリットの説明を作成します。
 
### 具体例

具体例を一つ挙げてみます。
あるインスタンス変数をローカル変数に変更する指摘をしたとします。
これが、他のインスタンス変数にも適用すべきかどうか、レビュイーは判断に迷うと思います。

そこでChatGPTをつかって「インスタンス変数よりローカル変数を使ったほうがいい理由」を作成します。

![image (1).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/15964/77ccfcd0-d2e8-5dc1-fea2-fe720c71fa2c.png)

最初の項目だけで、一般論として、ローカル変数の方がインスタンス変数より好ましいことがわかります。
レビュワーは、この説明をレビューコメントにコピペして添えます。

ソースコードレビューの第二の目的「レビュワーからレビュイーへ、ソフトウェア開発知識の共有」を諦めることなく、ソースコードレビューの時間を節約できます。