スムーズなコードレビューを行うために
（2021/05/27 更新しました）
仕事でも、メンターとしても、コードレビューを行っていますが、スムーズにレビューを行うためにいくつかお作法というか、コツがあります。今後レビューをお願いするときには、以下のことを配慮して依頼すると、スムーズにレビューしてもらえるかなーと思います。
コードのフォーマットを揃える
- コードのフォーマットをレビューアーと揃えておくと、スムーズにレビューが行えます。まずは、言語やプラットフォームの標準や、デファクトスタンダードに従うことをオススメします。わからない場合はメンターに聞いてみましょう。
- とはいえ好みもあるので、そこはレビューアーと相談します。例えばインデントだと、Space なのか、Tab なのか、2 つなのか、4 つなのか、などをすり合わせておきます。
- ルールを設定ファイル等で定義した上で、それを共有するとなお良いです。EditorConfig などを導入すると、エディタが異なる場合でも同じフォーマットに揃えてくれます。
- リンターやコードフォーマッターなどを導入するのも良い方法です。Web フロントエンドだと、ESLint が有名なリンターです。コードフォーマッターだと Prettier などがあります。
デバック環境構築のドキュメントを書く
- どのようにローカル環境でデバッグするかを README に記載しておくと、スムーズにデバッグが開始できます。
- インストールすべきツールとそのバージョン、実行手順、正しく動作したことを確認する方法を記載しておけば、ひとまず大丈夫だと思います。質問されたら、随時追記しておくと良いでしょう。
- README は、プロジェクトルートに
README.mdという名前で保存し、マークダウンで記載すると、GitHub のページに表示されます。
エラー／ワーニングがない状態でレビューを依頼する
- コンパイラやリンターのエラー／ワーニングを極力なくして、なるべく動作する（コンパイラが通る）状態で共有すると、課題が明確になって良いです。もちろん、エラーの解消を依頼する場合はこの限りではないです。
- 一度に多くの変更を行うと、あとでエラーをとるのが難しくなります。エラーが増えないように少しずつ実装するのがコツです。
不要なコードは極力残さない
- 動作とは関係のないコードは極力残さず、簡潔なコードにすることをお勧めします。
- あとで使うかもしれないコードを残したい気持ちもわかりますが、Git が使えれば、別のブランチで残しておいたり、過去に戻ることもできるので、思い切って削除しましょう。
- 不要なコメントアウトも、たくさん残っているとコードの見通しが悪くなるので、極力削除します。
- Git が使えない場合などでは、別のファイルにメモとして残しておいても OK です。極力コードは簡潔に保ちましょう。
コメントを書く
- 変数や関数だけでも、何を目的としているのかをコメントとして書くだけで、他の人が理解しやすくなります。
- 困っていることや自信がないこと、あとで対応することなどもコメントで記載しておくと、レビューアーが状況・背景を理解しやすいですし、あとで見る自分のためにも有効です。
- ドキュメントのように完璧さを求めると疲れるので、頑張りすぎないのもポイントです。
共有方法
- GitHub や Bitbucket などが使えれば、プルリクエストを送ってレビューしてもらったり、URL でコードを指定できるので便利です。Private リポジトリでも、コラボレーターとしてレビューアーを追加すれば共有することができます（GitHub のドキュメント）。
- GitHub 等を使えない場合は、ファイル一式すべてを Zip 等でアーカイブしてから共有します。たとえ１つのファイルだけしか変更していなくても、レビューアーが手元でマージする際にミスしてしまうこともあるので、動作するプロジェクト単位で Zip して共有する方が良いでしょう。
- 隠しファイルなどが抜けてしまうので、必ずフォルダごと Zip します。
- ローカルに保存した外部ライブラリなどはサイズが大きいので、除外して共有します。例えば Node.js だと、
node_modules/ディレクトリです。GitHub でシェアする場合は、.gitignoreに追加して、共有しないようにします。 - アカウント情報やパスワードなどは、共有可能なテストアカウントなどを設定すると良いです。
コードレビューの経験がない方は、最初にレビュー依頼方法についてメンターに相談してみると良いと思います。
ちなみに、私もコードレビューのプランをご用意しておりますので、ぜひご検討ください！
https://menta.work/plan/1114
