概要
本ドキュメントでは、コードレビューをする上での指針を以下3点について述べる。
- コードレビューを行うタイミング
- コードレビューの観点
- レビューコメントをする上での注意点
また、本ドキュメントは以下の文献を参考にしている。
https://google.github.io/eng-practices/review/
https://google.github.io/eng-practices/review/reviewer/
https://www.ipa.go.jp/security/awareness/vendor/programmingv2/contents/c103.html
https://employment.en-japan.com/engineerhub/entry/2018/04/03/110000
コードレビューを行うタイミング
原則コードレビューはモジュール1つの実装完了時、もしくはissue1項目対応完了時に行う。
コードレビューの観点
設計
コードが適切な設計をなされているかどうかを議論する。具体例として、以下の項目を示す。
- モジュール分割が十分細かく行われていること
- ひとつの関数の行数が多過ぎないこと
- Assertが記述されていること:詳細はこちらを参照のこと。
- ループが有限回数で停止すること
- 再起呼び出しが有限の深さで停止すること
- 外部から取り込むデータすべてに入力検査を施していること
- 並列プログラムである場合、競合状態やデッドロックにならないこと
- DRY原則を満たすこと
- SOLID原則を満たすこと
- その他ソフトウェア設計の原則に従っていること:リーダブルコード、97のことを読むとよい。
- 複雑すぎず、別の開発者や未来の自分たちが簡単に理解し、使用、改修を行うことができること
機能性
書いたコードは開発者の意図通りに動作するか、ユーザーにとっての使い心地はどうかを議論する。
原則、レビュイーはコードレビューを依頼する前にテストと動作確認を済ませておく。
レビュー時に問題を発見した場合には、レビュアーはコードをレビュイーに差し戻す。
テスト
レビューされるコードには、原則テストコードを合わせて記述し、テストが通ることを確認する。
テストコードに対しても、コードレビューとテストの妥当性検証を合わせて行う。レビュアーは考慮漏れやエッジケースを提案できると望ましい。
ソフトウェア開発におけるテストについてはこちらを参考にするとよい。
命名
変数、関数などの各種アイテムが何であるか、何を行うかが明確にわかるような名前がつけられているかを議論する。
一般的な命名規則については、リーダブルコードを参照するとよい。プログラミング言語またはプロジェクトで命名規則が明示されている場合にはそれに従う。
コメント
適切なコメントが適切な箇所に加えられているかを議論する。
コードを読めば自明な処理についてはコメントを記載する必要はない。数学、通信などの専門技術を要する処理、複雑なアルゴリズム、正規表現などには適宜コメントを記載する。
スタイル
プロジェクトでコーティング規約が定められている場合はそれに従う。そうでない場合はチームでコーティング規約を定めるか、プログラミング言語や開発環境で推奨されるコーティング規約に従う。例:Googleのスタイルガイド
コーティング規約に沿ったコードフォーマッタや静的解析ツールをチーム内で共有する。開発用のリポジトリにあげておくとよい。例:editorconfig、ClangFormatなどの各種フォーマッタ、各種lint。
ドキュメント
コードに合わせて、ドキュメントも更新しているかどうかを確認する。
開発環境、テスト、デプロイ、実行方法についてREADMEに記載する。
必要に応じてDoxygen等のドキュメント出力ツールを用いる。
レビューコメントをする上での注意点
- 意図がわからないコードについて質問する。
- 指摘箇所に対するコメントには指摘理由を明確かつ丁寧に述べる。
- 必要に応じてより良いコードを書くためのガイダンスやアドバイスを提示する。
- 良いところに関してもコメントするようにする。