音声入力でコードレビューのコメントをすばやく書く

役立つコードレビューのコメントには、気になる箇所だけでなく、どんな動作が問題なのか、なぜ重要なのか、次に何をしてほしいのかが書かれています。「空の場合に対応してください」だけでは、意図を確認するやり取りが必要になるかもしれません。一方、その説明を何度も入力すると、レビューの流れが途切れがちです。

音声入力なら、考えがまとまっているうちに説明を下書きできます。Macで差分を表示したままコメント欄を開き、同僚に説明するつもりで話し、投稿前に文章を整えましょう。音声入力が行うのは説明の文字化です。コードの検証や変更の正しさの判断は、レビューする人が行います。

1. 話す前に根拠を整理する

一つのコメントで扱う論点を一つに絞ります。対象の行や関数、入力値や状況、確認した動作、期待する動作を整理しましょう。実行していない場合は、コードを読んだうえでの懸念だと明記します。起こり得る問題と、再現済みの不具合を区別することが大切です。

相手に求める対応も決めます。

• 修正依頼： 承認前に解決が必要な具体的な問題や、合意済みの要件を示します。
• 提案： 任意の改善であることを明確にします。
• 質問： 修正が必要か判断できないときに、背景や意図を確認します。

区分はチームの運用に合わせましょう。個人的な好みを、強い言い方だけで必須の修正にしてはいけません。

2. 理由を話し、正確な表記は後から入れる

「この状況では、こう動きます。その結果、こういう影響があります。この変更や確認はできますか」という順番で説明します。話のまとまりごとに間を置き、一度に複数の論点を詰め込まないようにします。

関数名、ファイルパス、コード片は、下書きの後にソースから正確に挿入しましょう。記号一つで意味が変わるコードは、音声認識だけに任せません。重複を削り、人への評価ではなく、実装とその影響について書きます。

3. 曖昧なメモを具体的なコメントに変える

以下は、レビュアーがローカル環境で動作を再現した架空の例です。

最初のメモ：「検索が空の場合を直す必要がある」

編集後のコメント：

修正依頼 — 空の検索： 空白文字だけを入力して検索すると、結果欄が読み込み中のままになります。今回の変更をローカル環境で実行して再現しました。利用者には検索結果も、次に何をすればよいかという案内も表示されません。

検索開始前に空白文字だけの入力を処理し、合意済みの未入力時メッセージを表示できるでしょうか。この経路のテストも追加して、読み込み中の状態が適切に解除されることを確認したいです。

未検証なら「この分岐を読む限りでは、〜の可能性があるように見えます」と書き、別の経路で対応していないか確認します。表示内容が未合意なら、要件を決めつけず、期待する動作から相談しましょう。

4. 短いテンプレートを活用する

種類： ［修正依頼／提案／質問］

状況： ［箇所や条件］で、［確認した動作、または懸念であると明記した内容］。

影響： ［具体的な結果］につながります。

次の対応： ［変更、検証、説明］をお願いできますか。

根拠： ［再現手順、関連要件、テスト結果があれば記載］。

毎回すべての見出しを使う必要はありません。小さな提案なら2文で十分なこともあります。複数ファイルにまたがる論点は、各行に同じ指摘を繰り返すより、レビュー全体のコメントにまとめて関連箇所を示すと伝わりやすくなります。

5. 投稿前に意味と根拠を確認する

名前、否定表現、専門用語を差分と照合します。「する」が「しない」になっていないか、書いたテスト結果は実際に確認したものかを見直しましょう。相手が次に何をすべきか、意図を推測しなくてもわかる文章になっているか確認します。

関連する作業には、プルリクエストの説明文を書く方法とわかりやすい不具合報告の作り方も役立ちます。

TypeFreeは、話した内容を編集可能なテキストに変え、文章をすばやく書くためのシンプルな方法です。次のコードレビューでは、指摘の理由を声で下書きし、詳細を確認して、相手が対応しやすいコメントに仕上げましょう。