🪄
Google コードレビュー・ガイドライン要約【コメントの書き方編】
はじめに
本記事は「Google コードレビュー・ガイドライン要約」シリーズの【コードレビューの進め方編】です。
Google Engineering Practices Documentation (日本語訳) の要約になります。
未読の方は、はじめに 本記事のポジションと用語 をお読みください。
シリーズ構成
※リンクが貼られていない箇所は未要約です
- コードレビューの仕方
- コードレビューの基準
- コードレビューの観点
- コードレビューの進め方
- コードレビューのスピード
- コメントの書き方 ← here!!
- 取り下げへの対応
- CL 作成者のガイド
- 適切なディスクリプション
- 小さな CL
- レビューコメントへの対応
- 緊急事態の CL
レビューコメントの書き方
先にまとめ
- コメントは丁重に書く
- 理由を説明する
- 解決の明確な方向性を示ことと、開発者本人に決定を委ねることを、バランスよく行う
- 複雑なコードを見つけたらそれを説明してもらうだけで終わらせず、コードをシンプルにすることやコードにコメントを追加することを開発者に勧める
礼儀正しさ
- 敬意を払う
- コメントは礼儀正しく、敬意を払った書き方であることは大切である
- もちろん、明確で有益な内容であることも大切である
- 必ずコードについてコメントし、開発者本人についてコメントしない
- この慣例に杓子定規に従う必要はない
- 相手を傷つけたり怒らせたりするかもしれない繊細な内容を書くときには、必ず従う
- 悪い例
並行処理にしても明らかにメリットがないのに、どうしてあなたはスレッドを使ったのですか？
- 良い例
見たところ、ここで使った並行処理モデルは実際にはパフォーマンス上のメリットがないまま、ただシステムを複雑にしています。
パフォーマンス上のメリットがないので、複数スレッドを使わずにシングルスレッドのコードにするのが最善です
- コメントは礼儀正しく、敬意を払った書き方であることは大切である
「なぜ」を説明する
- なぜそうするのか
- あなたが書いているコメントの「理由」を開発者が理解することは有益である
- 例えば、こんなことができる
- コメントの意図についてもう少し詳しく説明する
- あなたが参考にしているベストプラクティスを教える
- あなたの提案が、どのようにコードの健全性を良くするのかを解説する
指示を与える
- 問題提起と指示のバランス
- レビュアーは、問題を指摘することと直接指示を与えることを、適度にバランス良く行う
- レビュアーは、手助けしないでただ突き放せばよいということはない
- 開発者に任せることの意義
- しばしば開発者が自分で学ぶ機会になる
- 開発者はよりコードを間近で見ているので、任せるほうが良いソリューションになることもある
- 直接指示することの意義
- ときにはコードを見せることがさらに有益になる場合もある
- コードレビューの主な目的
- CL の健全性をできる限り良くすること
- 開発者のスキルを向上させ、長期的にレビューを不要にすること
説明を受け入れる
- コードを理解できないとき
- 多くの場合、コードをより明確に書き直してもらう方が良い結果になる
- ときには、複雑すぎるコードにコメントを追加するのも適切な応答になる
- コードにコメントを残す
- コードレビューツールの中に説明を残しても、将来そのコードを読む人にとっては役に立たない
- ツールにコメントを残すのが受け入れられるケースは、限られた状況だけ
- あなたがあまり詳しくなく、通常そのコードを読む開発者はすでによく知っているような情報を説明してもらうとき
おわりに
礼儀正しさ、大切ですよね。教育的な部分に触れいていることも印象的でした。
ただ、「良い例」の内容は、もう少し寄り添っても良いような...笑
理由を説明することは、より良いコードを書く上で議論するために、かなり重要だと考えています。
Discussion