├── .gitignore ├── .vscode └── settings.json ├── LICENSE ├── README.md ├── _config.yml ├── googlea6490cfbbfe4fe0e.html ├── inalz.yml ├── index.md ├── ja └── review │ ├── developer │ ├── cl-descriptions.md │ ├── handling-comments.md │ ├── index.md │ └── small-cls.md │ ├── emergencies.md │ ├── index.md │ └── reviewer │ ├── comments.md │ ├── index.md │ ├── looking-for.md │ ├── navigate.md │ ├── pushback.md │ ├── speed.md │ └── standard.md ├── locales ├── index.yml └── review │ ├── developer │ ├── cl-descriptions.yml │ ├── handling-comments.yml │ ├── index.yml │ └── small-cls.yml │ ├── emergencies.yml │ ├── index.yml │ └── reviewer │ ├── comments.yml │ ├── index.yml │ ├── looking-for.yml │ ├── navigate.yml │ ├── pushback.yml │ ├── speed.yml │ └── standard.yml ├── package-lock.json ├── package.json └── review ├── developer ├── cl-descriptions.md ├── handling-comments.md ├── index.md └── small-cls.md ├── emergencies.md ├── index.md └── reviewer ├── comments.md ├── index.md ├── looking-for.md ├── navigate.md ├── pushback.md ├── speed.md └── standard.md /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | lerna-debug.log* 8 | 9 | # Diagnostic reports (https://nodejs.org/api/report.html) 10 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 11 | 12 | # Runtime data 13 | pids 14 | *.pid 15 | *.seed 16 | *.pid.lock 17 | 18 | # Directory for instrumented libs generated by jscoverage/JSCover 19 | lib-cov 20 | 21 | # Coverage directory used by tools like istanbul 22 | coverage 23 | *.lcov 24 | 25 | # nyc test coverage 26 | .nyc_output 27 | 28 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 29 | .grunt 30 | 31 | # Bower dependency directory (https://bower.io/) 32 | bower_components 33 | 34 | # node-waf configuration 35 | .lock-wscript 36 | 37 | # Compiled binary addons (https://nodejs.org/api/addons.html) 38 | build/Release 39 | 40 | # Dependency directories 41 | node_modules/ 42 | jspm_packages/ 43 | 44 | # TypeScript v1 declaration files 45 | typings/ 46 | 47 | # TypeScript cache 48 | *.tsbuildinfo 49 | 50 | # Optional npm cache directory 51 | .npm 52 | 53 | # Optional eslint cache 54 | .eslintcache 55 | 56 | # Optional REPL history 57 | .node_repl_history 58 | 59 | # Output of 'npm pack' 60 | *.tgz 61 | 62 | # Yarn Integrity file 63 | .yarn-integrity 64 | 65 | # dotenv environment variables file 66 | .env 67 | .env.test 68 | 69 | # parcel-bundler cache (https://parceljs.org/) 70 | .cache 71 | 72 | # next.js build output 73 | .next 74 | 75 | # nuxt.js build output 76 | .nuxt 77 | 78 | # vuepress build output 79 | .vuepress/dist 80 | 81 | # Serverless directories 82 | .serverless/ 83 | 84 | # FuseBox cache 85 | .fusebox/ 86 | 87 | # DynamoDB Local files 88 | .dynamodb/ 89 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "editor.tokenColorCustomizations": { 3 | "[dark-plus-syntax]": { 4 | "textMateRules": [ 5 | { 6 | "scope": [ 7 | "string", 8 | "string.tag", 9 | "string.value", 10 | "meta.preprocessor.string" 11 | ], 12 | "settings": { 13 | "foreground": "#d4d4d4" 14 | } 15 | } 16 | ] 17 | } 18 | }, 19 | "yaml.completion": false, 20 | } 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Google Engineering Practices Documentation 2 | 3 | Google has many generalized engineering practices that cover all languages and 4 | all projects. These documents represent our collective experience of various 5 | best practices that we have developed over time. It is possible that open source 6 | projects or other organizations would benefit from this knowledge, so we work to 7 | make it available publicly when possible. 8 | 9 | Currently this contains the following documents: 10 | 11 | * [Google's Code Review Guidelines](review/index.md), which are actually two 12 | separate sets of documents: 13 | * [The Code Reviewer's Guide](review/reviewer/index.md) 14 | * [The Change Author's Guide](review/developer/index.md) 15 | 16 | ## Terminology 17 | 18 | There is some Google-internal terminology used in some of these documents, which 19 | we clarify here for external readers: 20 | 21 | * **CL**: Stands for "changelist," which means one self-contained change that 22 | has been submitted to version control or which is undergoing code review. 23 | Other organizations often call this a "change" or a "patch." 24 | * **LGTM**: Means "Looks Good to Me." It is what a code reviewer says when 25 | approving a CL. 26 | 27 | ## License 28 | 29 | The documents in this project are licensed under the CC-By 3.0 License, which 30 | encourages you to share these documents. See 31 | https://creativecommons.org/licenses/by/3.0/ for more details. 32 | 33 | Creative Commons License 34 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-slate 2 | -------------------------------------------------------------------------------- /googlea6490cfbbfe4fe0e.html: -------------------------------------------------------------------------------- 1 | google-site-verification: googlea6490cfbbfe4fe0e.html 2 | -------------------------------------------------------------------------------- /inalz.yml: -------------------------------------------------------------------------------- 1 | lang: 2 | source: en 3 | targets: 4 | - ja 5 | documents: 6 | - source: review 7 | targets: 8 | ja: ja/review 9 | locale: locales/review 10 | - source: README.md 11 | targets: 12 | ja: index.md 13 | locale: locales/index.yml 14 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | # Google Engineering Practices Documentation (日本語訳) 2 | 3 | Google には、全言語および全プロジェクトをカバーする広範なエンジニアリングの慣行があります。 4 | ここにあるドキュメントは私達が長年の経験からさまざまなベストプラクティスを蓄積してきたことを表しています。 5 | この知識がオープンソースプロジェクトや他の組織の利益になることを願って、私達は可能ならそれを誰にでも利用できるように公開します。 6 | 7 | 現在、以下のドキュメントがあります。 8 | 9 | - [Google コードレビューガイドライン](ja/review/index.md)。これは 2 つのドキュメントからなります。 10 | - [コードレビュアーのガイド](ja/review/reviewer/index.md) 11 | - [変更作成者のガイド](ja/review/developer/index.md) 12 | 13 | ## 用語 14 | 15 | ここにあるドキュメントには、Google 内部で使われる用語があります。外部の読者のために意味を掲載しておきます。 16 | 17 | - **CL**: 「changelist」の略。一つの独立した変更を意味していて、バージョン管理に提出されたものや、まだコードレビュー中のものを指すこともあります。他組織では「変更」「パッチ」とよく呼ばれます。 18 | - **LGTM**: 「Looks Good to Me」という意味。コードレビュアーが CL を承認するときに言う。 19 | 20 | ## ライセンス 21 | 22 | このプロジェクトのドキュメントは CC-By 3.0 License の下にあります。ここにあるドキュメントをぜひシェアしてください。詳細は https://creativecommons.org/licenses/by/3.0/ をご覧ください。 23 | 24 | Creative Commons License 25 | -------------------------------------------------------------------------------- /ja/review/developer/cl-descriptions.md: -------------------------------------------------------------------------------- 1 | # 適切な CL のディスクリプションを書く 2 | 3 | CL のディスクリプションは**何**が変更され、**なぜ**変更されたのかを説明する公式記録です。この記録はバージョン管理の履歴に永続的に残され、長期にわたって読まれます。レビュアー以外にも数百人もの人が読むこともあります。 4 | 5 | 将来の開発者はあなたの CL をディスクリプションに基づいて検索します。将来の誰かがあなたの作成した変更を見つけようとして、詳細は忘れているけれどもその変更に関するおぼろげな記憶を頼りに検索するかもしれません。重要な情報がすべてコードにだけ書かれていてディスクリプションに記載されていないと、探している CL を見つけるのが非常に難しくなるでしょう。 6 | 7 | ## 一行目 {#firstline} 8 | 9 | - 何を行っているのかを短く要約する 10 | - 完全な文で、命令形で書く 11 | - 次の行は空行にする 12 | 13 | CL の**一行目**には、その CL が**何**を行っているのかを明確に記した短い要約を書いてください。二行目は空行にしてください。将来コードを検索する人はコードのバージョン管理履歴を拾い読みするのにまずこの箇所を読むことになります。そのときにあなたの CL が何を**した**のか概要をつかむために CL のコードやディスクリプション全体を読まなくて済むように、一行目にしっかりと有益な情報を盛り込んでください。 14 | 15 | 慣習的に、CL のディスクリプションの一行目は完全な文で、命令のように (命令形で) 書きます。たとえば、「**Deleting** the FizzBuzz RPC and **replacing** it with the new system.」と書くのではなく「**Delete** the FizzBuzz RPC and **replace** it with the new system.」と書きます。もっとも、ディスクリプションの他の部分まで命令形で書く必要はありません。 16 | 17 | ## 主要部に有益な情報を盛り込む {#informative} 18 | 19 | 二行目以降のディスクリプションには有益な情報を盛り込んでください。解決されている問題に関する短い説明を書くこともありますし、なぜこれが最良の方法なのかを説明することもあります。その方法に欠陥があれば、その点にも言及してください。また関連があれば、バグチケットの番号やベンチマーク結果、設計ドキュメントのリンク等の背景も書いてください。 20 | 21 | 小さな CL であっても詳細に書くよう心がける価値があります。CL をコンテキストの中に位置付けてください。 22 | 23 | ## CL ディスクリプションの悪い例 {#bad} 24 | 25 | 「Fix bug」とだけ書いた CL ディスクリプションは情報量不足です。どんなバグでしょうか？バグを修正するために何をしたのでしょうか？他にも悪いディスクリプションの例を以下に示します。 26 | 27 | - "Fix build." 28 | - "Add patch." 29 | - "Moving code from A to B." 30 | - "Phase 1." 31 | - "Add convenience functions." 32 | - "kill weird URLs." 33 | 34 | いくつかのものは実際にあった CL ディスクリプションです。作成者は有益な情報を提供しているつもりかもしれませんが、上の例は CL ディスクリプションの目的を果たせていません。 35 | 36 | ## 適切な CL ディスクリプションの例 {#good} 37 | 38 | 以下は適切なディスクリプションの例です。 39 | 40 | ### 機能変更 41 | 42 | > rpc: RPC サーバーのメッセージフリーリストのサイズ制限を取り除く。(訳注: 英語では命令形) 43 | > 44 | > FizzBuzz のようなサーバーには巨大なメッセージがあり、再利用することでメリットがある。フリーリストを大きくし、徐々にフリーリストエントリーを解放する goroutine を追加することで、アイドリング中のサーバーが最終的にすべてのフリーリストエントリーを解放するようにした。 45 | 46 | 最初の文で CL が実際に何をするのかを説明しています。以降のディスクリプションでは、解決される問題となぜこれが適切な解決なのか、また特定の実装に関する付加情報を記述しています。 47 | 48 | ### リファクタリング 49 | 50 | > TimeStr と Now メソッドを使用するため Task を TimeKeeper と一緒に初期化する。(訳注: 英語では命令形) 51 | > 52 | > Task に Now メソッドを追加することで、borglet() getter method を除去できるようにする (これは OOMCandidate が borglet の Now メソッドを呼び出すために使うだけだった)。これは TimeKeeper に委譲する Borglet のメソッドを置き換える。 53 | > 54 | > Task に Now を与えられるようにするのは Borglet への依存をなくすための一ステップである。最終的には Task から Now を取得することに依存している部分は TimeKeeper を直接使うように変更すべきだが、これはスモールステップでリファクタリングするための調整である。 55 | > 56 | > Borglet の階層構造をリファクタリングする長丁場のゴールに向けて引き続き作業する。 57 | 58 | 一行目は CL が何をするのかとどのような変更なのかを説明しています。以降のディスクリプションでは特定の実装と CL のコンテキストを説明しています。CL のソリューションは理想的ではないものの将来の方向性を示しています。またこの説明では**なぜ**この変更が行われるのかにも言及しています。 59 | 60 | ### コンテキストの説明が必要な小さな CL 61 | 62 | > status.py の Python3 ビルドルールを作成する (訳注: 英語では命令形) 63 | > 64 | > これにより、Python3 ですでにそうしているようにこれを使用しているユーザーが自分の tree の中を探さなくても規定の status ビルドルールの隣のルールに依存できるようになる。そのことで新しいユーザーには可能なら Python2 ではなく Python3 を使用するよう促し、現在作業中の自動化されたビルドファイルのリファクタリングツールが有意に単純化される。 65 | 66 | 一文目は何が実際に行われているのかを説明しています。以降のディスクリプションでは**なぜ**その変更が行われるのかを説明し、レビュアーに十分なコンテキストを提供しています。 67 | 68 | ## CL を提出する前にディスクリプションをレビューする 69 | 70 | CL はレビューの間、重要な変更を被ることがあります。CL を提出する前に CL ディスクリプションをレビューするのが有意義な場合があります。それはディスクリプションが CL の内容を正しく反映してることを確認するためです。 71 | 72 | 次: [小さな CL](small-cls.md) 73 | -------------------------------------------------------------------------------- /ja/review/developer/handling-comments.md: -------------------------------------------------------------------------------- 1 | # レビューコメントの対応の仕方 2 | 3 | CL をレビューに送ると、レビュアーが CL にいくつかのコメントを残してくれます。ここではレビュアーのコメントに対応するときに知っておくと有益なポイントを紹介します。 4 | 5 | ## 個人の人格へのコメントとして受け取らない {#personal} 6 | 7 | レビューの目的は私達のコードベースと私達のプロダクトの品質を維持することです。レビュアーがあなたのコードに苦言を呈したら、それを個人攻撃とかあなたの能力をくさしているとか受け取らずに、レビュアーがあなたを手助けしようとしていると考えてみてください。レビュアーはコードベースを、また Google を良くしようとしているのです。 8 | 9 | ときにはレビュアーが苛立って、そのイライラをコメントに表現することもあります。これはレビュアーとして褒められた行いではありませんが、開発者としてはこうしたことへの心構えをしましょう。ご自分にこう問いかけてください。「レビュアーが私に伝えようとしている建設的な事柄は何だろう？」と。そして、それがレビュアーの真意だと捉えてください。 10 | 11 | **コードレビューコメントに対して怒りに任せて反応しないでください。**怒りに任せたコメントはプロとしての礼儀作法に違反しますし、それがコードレビューツールに永遠に残ることになります。もしあなたが怒りや苛立ちで丁重に応答できなくなっていれば、しばらく席を立って歩いたり他の作業に当たったりして、気持ちが落ち着いて丁重な応答ができるようになるのを待ってください。 12 | 13 | 一般に、レビュアーが建設的で礼儀正しい言い方でフィードバックをしてくれない場合、そのことを対面で伝えましょう。対面やビデオ通話で会話する機会が持てなければ、個人的なメールを送りましょう。レビュアーの言い方のどこが嫌でどんなふうに変えてほしいのかを丁重に説明してください。この個人的な会話でもレビュアーが非建設的な言い方で応酬するようなら、あるいは態度が全く変わらないようなら、上司に相談するのが適切です。 14 | 15 | ## コードを修正する {#code} 16 | 17 | レビュアーがあなたのコードに理解できない箇所があると言うなら、最初に行うべきはコード自体を明確にすることです。コードを明確にできないなら、なぜそのコードがそこにあるのか理由を書いたコメントをコードに追加してください。コメントの追加では足りない場合に限り、コードレビューツール上で説明してください。 18 | 19 | レビュアーがあなたのコードを理解できければ、将来コードを読む人も理解できない可能性が高いです。コードレビューツール上で説明しても将来コードを読む人には役立ちませんが、コード自体を整理したりコードにコメントを追加したりすれば、将来コードを読むにも役立ちます。 20 | 21 | ## 自分で考える {#think} 22 | 23 | CL を書くのは大きな労力が伴います。CL をレビューに送り出すとすっかり満足して、これで仕事が完了したと感じ、これ以上作業が必要ないと思い込んでしまうことがよくあります。そうなるとレビュアーが改善点についてコメントを返しても、コメントのほうが間違っていて、レビュアーがあなたを不必要にブロックしているとか、つべこべ言わずに CL を取り込んでくれればいいのにとか反射的に考えてしまいやすいものです。けれども、そのときに**どれだけ自分が正しいと確信していたとしても**、少し立ち止まって、レビュアーがコードベースと Google を良くする価値あるフィードバックを書いているのではないかと考えてみてください。常日頃から「レビュアーが正しいのではないか？」と自問自答してください。 24 | 25 | その問いに答えを出せないとしたら、レビュアーのコメントがわかりにくいのが原因と考えられるので、レビュアーがもっと明解に書く必要があります。 26 | 27 | その問いを**考えた**上でなお自分が正しいと思えるなら、あなたのやり方のほうがコードベースにとってもユーザーにとっても、また Google にとっても良いといえる理由を気兼ねなく説明してください。レビュアーは実際には**提案**をしていて、何が最良なのかは開発者自身に考えてほしいと思っていることがよくあります。開発者はユーザーについて、コードベースについて、CL についてレビュアーの知らないことを知っていることもあります。そういうときには知識のギャップを埋めてください。レビュアーにコンテキストをもっと与えてください。技術的な事実に基づいて開発者とレビュアーの間で一定のコンセンサスに達することができるでしょう。 28 | 29 | ## 意見の対立を解消する {#conflicts} 30 | 31 | 意見の対立を解消するためにまず行うべきはレビュアーとコンセンサスを得られるよう試みることです。コンセンサスに達することができない場合、[コードレビューの基準](../reviewer/standard.md)にそういった状況で対応する際の原則があるので参考にしてください。 32 | -------------------------------------------------------------------------------- /ja/review/developer/index.md: -------------------------------------------------------------------------------- 1 | # コードレビューを通過するための CL 作成者のガイド 2 | 3 | このセクションでは、開発者がコードレビューにパスするためのベストプラクティスを説明します。ここにあるガイドラインは開発者がコードレビューを素早く通過し、品質の高い結果を残すのに役立つでしょう。すべてを読む必要はありませんが、このガイドラインは Google の全開発者に適用できるように作られているため、全体を通して読むのが有益であるという感想を持つ人が多いです。 4 | 5 | - [適切な CL のディスクリプションを書く](cl-descriptions.md) 6 | - [小さな CL](small-cls.md) 7 | - [レビューコメントの対応の仕方](handling-comments.md) 8 | 9 | [コードレビューの仕方](../reviewer/)も参考にしてください。こちらはコードレビュアーのための詳細なガイドです。 10 | -------------------------------------------------------------------------------- /ja/review/developer/small-cls.md: -------------------------------------------------------------------------------- 1 | # 小さな CL 2 | 3 | ## どうして小さな CL を書くのか？ {#why} 4 | 5 | 小さくシンプルな CL には以下のような利点があります。 6 | 7 | - **速くレビューできる。**レビュアーにとって、小さな CL をレビューするための 5 分間を数回確保するほうが、一度の大きな CL をレビューするための 30 分をまとめて確保するよりも容易です。 8 | - **隅々までレビューできる。**変更が大規模だとあっちこっちに詳細なコメントを大量に書かねばならず、レビュアーと作成者がストレスを感じやすくなります。ときには重要な点を見落としたり省略したりしてしまうこともあります。 9 | - **バグが混入する可能性が減る。**変更箇所が少なければ、開発者もレビュアーも CL の影響範囲が予測しやすく、バグが混入したかどうかを見分けやすくなります。 10 | - **CL が却下されても無駄になる作業が少ない。**巨大な CL を書いてからレビュアーに全体的な方向性が間違っていると言われると、多くの作業が無駄になってしまいます。 11 | 12 | - **マージしやすい。**大規模な CL での作業には時間がかかるため、マージする頃には多くのコンフリクトが発生し、頻繁にマージしなければならなくなります。 13 | - **設計を改善しやすくなる。**小さな変更の設計やコードの健康状態を改善するほうが、大きな変更の詳細をすべて見直して設計を洗練させるよりもずっと簡単です。 14 | - **レビューによって作業がブロックされなくなる。**あなたがしようとしている変更全体のうち一部を自己完結的な CL にして提出すれば、現在の CL のレビューを待つ間にコーディング作業を続けることができます。 15 | - **ロールバックしやすい。**大きな CL は多くのファイルにわたって変更するため、最初に CL を提出してからロールバックの CL までにそれらのファイルが変更され、ロールバックが複雑になります。（その CL 以降の CL もロールバックする必要が生じることもあります） 16 | 17 | 注意していただきたいのですが、**レビュアーにはあなたの変更が大きすぎるというそれだけの理由でただちにその変更を却下できる裁量があります。**普通はそこまでせず、レビュアーはあなたの貢献に感謝しつつも、もっと小さな変更に分けて CL を送ってほしいとリクエストするでしょう。すでにコードを書いたあとで変更を分割するのは骨の折れる作業になりますし、あるいは巨大な変更を受け入れてもらうにしてもレビュアーが納得できるよう議論を交わすのにも多くの時間が必要になります。最初から小さな CL を書くほうが簡単です。 18 | 19 | ## 「小さい」とはどういうことか？ {#what_is_small} 20 | 21 | 一般に、CL の適切なサイズは**単一の自己完結的な変更**です。これは以下のことを意味します。 22 | 23 | - CL が**ただ一つのこと**に取り組むミニマルな変更を行っています。これは普通、ある機能の全体を一度に実装するというより、その中の一部分だけを実装する CL です。小さすぎる CL を書いて失敗するほうが大きすぎる CL を書いて失敗するよりもよほど良いです。レビュアーと協力してどんなサイズの CL なら受け入れられるかを探ってみてください。 24 | - レビュアーがその CL について理解する必要のあるすべての情報 (将来の開発を除く) が CLや、CL ディスクリプション、既存のコードベース、これまでレビューした CL の中にあります。 25 | - システムはその CL がチェックインされたあともユーザーにとっても開発者にとっても正常に動作し続けます。 26 | - CL がその含意がわかりにくくなるほどに過剰に小さくはありません。新しい API を追加するのなら、同じ CL の中にその API の使い方を含めるべきです。それはレビュアーが API の使い方をきちんと理解できるようになるためです。こうすることは、使われていない API のチェックインを防止します。 27 | 28 | どれほど大きければ「大きすぎる」と言えるのかを判断する厳密で手っ取り早いルールはありません。大雑把には 100 行の CL は適度なサイズで、1000 行になると大きすぎると言えますが、これもレビュアーの判断次第です。変更するファイル数も CL の「サイズ」に関係あります。200 行の変更が行われていてもそれが 1 つのファイルで完結していれば許容できるかもしれませんが、 50 ファイルにもわたる変更であれば普通は「大きすぎる」と判断されるでしょう。 29 | 30 | 覚えておいていただきたいのですが、あなたはコードを書き始めた瞬間からコードに没頭していて目を閉じてもコードを思い浮かべられるとしても、レビュアーは何のコンテキストも持たないことがよくあります。あなたにとって許容範囲な CL のサイズのように思えても、レビュアーにとっては大きすぎるかもしれません。CL が小さすぎるからといってそのことで不満をこぼすレビュアーはめったにいません。 31 | 32 | ## どのようなときに大きな CL でも良いか？ {#large_okay} 33 | 34 | 大きな変更でも許される状況が例外的にあります。 35 | 36 | - 一つのファイルをまるごと削除する場合は、一行だけの変更とみなしても構いません。レビューするのにそれほど長い時間がかからないからです。 37 | - 大規模な CL がリファクタリングツールによって自動生成される場合があります。そのツールをあなたが完全に信頼していれば、そういった CL が大きくても構いません。レビュアーの仕事は正常に動作していることを確認して、意図通りに変更されていると言うだけです。このような CL は大きくなっても構いません。ただし、上で述べた注意書き（マージやテストなど）はこの場合にも適用されます。 38 | 39 | ### ファイルによる分割 {#splitting-files} 40 | 41 | CL を分割する他のやり方として、別々のレビュアーを必要とするという点を除けば自己完結的な変更となる複数のファイルをひとまとめにグループ分けするというのがあります。 42 | 43 | 例1: ある protocol buffer を修正する CL を一つ送り、その proto を使用するコードを変更する CL を別で送ります。proto 変更の CL をコード変更の CL よりも先に提出する必要がありますが、二つの CL は同時にレビューを受けられます。この場合、両レビュアーに変更のコンテキストを提供するため他方の CL に関する情報を知らせてもよいでしょう。 44 | 45 | 例2: コード変更の CL を一つ送り、そのコードを使用する構成や実験のために CL を別で送ります。このやり方では必要ならロールバックも容易にできます。構成・実験用のファイルはコード変更よりも素早くプロダクションにプッシュされることがあるからです。 46 | 47 | ## リファクタリングを分離する {#refactoring} 48 | 49 | 機能変更やバグ修正と、リファクタリングは別の CL にするのが普通はベストです。たとえば、クラスを移動したりクラス名を変更したりはそのクラスのバグ修正とは別の CL にするべきです。別々の CL に分けておけば、レビュアーは変更を理解しやすくなります。 50 | 51 | とはいえ、ローカル変数の名前を変えるといった小さな修正は機能変更やバグ修正の CL に含めても構いません。どんなときにリファクタリングが大きすぎるかは開発者とレビュアーの判断により決まります。リファクタリングを現在の CL に含めるとレビューがしにくくなるようなら、CL を分割してください。 52 | 53 | ## 関連するテストコードを同じ CL に含める {#test_code} 54 | 55 | テストコードを別の CL に分けるのは避けてください。コードの修正を検証するテストはコード変更の行数が増えるとしても同じ CL に入れてください。 56 | 57 | けれども、**独立した**テストの修正は別々の CL にして先に提出しても構いません。[リファクタリングのガイドライン](#refactoring)と同様です。たとえば以下のような場合です。 58 | 59 | - 提出済みの既存コードを新たなテストで検証する 60 | - テストコードのリファクタリング (例: helper 関数の導入) 61 | - より大きなテストフレームワークのコードの導入 (例: 統合テスト) 62 | 63 | ## ビルドを壊さない {#break} 64 | 65 | 相互に依存する複数の CL がある場合、CL の提出後もシステム全体が動作するようにする方法を見つける必要があります。そうしないと、すべての CL 提出が完了するまでの間にビルドを壊してしまい、同僚の開発者に迷惑をかけるかもしれません。(あるいは後の CL 提出に何か予期せぬ間違いがあると、ビルドの壊れた状態がもっと長引くこともあります。) 66 | 67 | ## 十分小さくできない場合 {#cant} 68 | 69 | CL を大きく**せざるをえない**ように思える状況になることがあります。非常に稀ですが、そういう状況は確かにあります。小さな CL を書く習慣が定着している開発者は、ほとんどどんな場合でも一機能を複数の小さな変更に分解する方法を見出すことができます。 70 | 71 | 大規模な CL を書く前に、事前にリファクタリングだけの CL を送ればもっとすっきりした実装をする方法が用意できるのではないかと考えてみてください。また、チームメンバーに相談し、その機能を小さな CL に分割できる実装方法を考えつくかどうか確認してみてください。 72 | 73 | 上記の施策でもうまく行かない場合 (非常に稀ですが)、大きな CL をレビューすることについて事前にレビュアーから同意を得てください。そうすればレビュアーはこれから来る CL の心構えができます。この状況では、レビュープロセスに時間がかかることが予想されます。バグを生み出さないよう細心の注意を払い、普段以上にテストをしっかり書いてください。 74 | 75 | 次: [レビューコメントの対応の仕方](handling-comments.md) 76 | -------------------------------------------------------------------------------- /ja/review/emergencies.md: -------------------------------------------------------------------------------- 1 | # 緊急事態 2 | 3 | 緊急の CL というものがときどきあります。緊急の CL は可能な限りすみやかにコードレビューの全プロセスを通過させる必要があります。 4 | 5 | ## 緊急事態とは何か？ {#what} 6 | 7 | 緊急の CL は**小さな**変更になるでしょう。たとえば、ローンチ済みの主要機能をロールバックするのではなく継続するための変更、本番環境のユーザーに重大な影響を与えるバグの修正、切迫した法的問題の対応、深刻なセキュリティホールの修正等です。 8 | 9 | 緊急事態で私達が尽力するのはレビューの[応答の速さ](reviewer/speed.md)だけでなくコードレビューのプロセス全体の速度です。この場合に**限り**、レビュアーはすみやかにレビューすることとコードの正確さ (緊急事態を本当に解決しているだろうか？) に何よりも集中してください。また、(当然かもしれませんが) このレビュー依頼が来たら他のレビューよりも最優先で取り組んでください。 10 | 11 | しかしながら、緊急事態が解決したあとは緊急の CL をもう一度見て、[全体的なレビュー](reviewer/looking-for.md)を再度行ってください。 12 | 13 | ## 緊急事態でないものは何か？ {#not} 14 | 15 | はっきりさせるために、緊急事態**でない**ものを以下に挙げます。 16 | 17 | - ローンチを来週から今週に早めたい (例外としてパートナーの同意のような[ハードな納期](#deadlines)が実際にある場合は別です) 18 | - 開発者がある機能について非常に長期間にわたって作業しているため、CL をそろそろいい加減取り込んでほしい。 19 | - レビュアーが皆、他のタイムゾーンにいて今は夜だったり現場にいなかったりする。 20 | - 今が金曜日の終業間際で、開発者が週末に去る前にこの CL を取り込んでもらえると素敵だ 21 | - マネージャーが [(ハードでなく) ソフトな納期](#deadlines)のためにこのレビューを今日中に完了させて CL を取り入れなければならないと言っている 22 | - テストの失敗やビルドの破壊を引き起こしている CL のロールバック 23 | 24 | 25 | 26 | ## ハードな納期とは何か？ {#deadlines} 27 | 28 | ハードな納期とはそれを逃すと**大きな損害が発生する**納期のことです。たとえば以下のようなものです。 29 | 30 | - 契約上の義務からある期日までに CL を提出する必要がある。 31 | - ある期日までにリリースしなければそのプロダクトが市場で完全に乗り遅れてしまう。 32 | - あるハードウェアメーカーは新しいハードウェアを年に一度しかリリースしない。納期までにコードを提出しないと、リリースしようとしているコードの種類によっては大きな損害が発生する。 33 | 34 | リリースが一週間遅れても大きな損害にはなりません。重要なカンファレンスを逃すと損害が大きくなるかもしれませんが、とはいえ頻繁に起こるケースではありません。 35 | 36 | ほとんどの納期はソフトな納期であって、ハードな納期ではありません。ある機能が期日までに実装されてほしいという願望を述べているだけです。それは重要ではありますが、そのためにコードの健康状態を犠牲にすべきではありません。 37 | 38 | リリースサイクルが数週間にわたる長い期間だったりすると、次のサイクルに入る前にコードレビューの品質を犠牲にしてまである機能を取り入れてしまいたいという誘惑があることがあります。けれども、このパターンが繰り返されると、プロジェクト技術的負債があるとき噴出することになります。開発者が CL をリリースサイクルの終盤に提出し、表面をなぞるだけのレビューで CL を「取り入れなければならない」といったことが習慣的に行われているなら、チームは開発プロセスを見直すべきです。大きな機能変更はリリースサイクルの初期に提出し、きちんとレビューするための時間を十分に確保できるようにしてください。 39 | -------------------------------------------------------------------------------- /ja/review/index.md: -------------------------------------------------------------------------------- 1 | # コードレビュー開発者ガイド 2 | 3 | ## はじめに {#intro} 4 | 5 | コードレビューとは、コードの作成者以外の人がコードを調べるプロセスです。 6 | 7 | Google ではコードとプロダクトの品質を維持するためにコードレビューを実施しています。 8 | 9 | このドキュメントは Google のコードレビューのプロセスとポリシーに関する正規の解説です。 10 | 11 | このページでは私達のコードレビュープロセスを概観します。このガイドはさらに二つのドキュメントに分けられます。 12 | 13 | - **[コードレビューの仕方](reviewer/)**: コードレビュアーのための詳細なガイド 14 | - **[CL 作成者のガイド](developer/)**: CL をレビューしてもらう開発者のための詳細なガイド 15 | 16 | ## コードレビュアーはどんな観点でレビューすべきか？ {#look_for} 17 | 18 | コードレビューは次の観点で見るべきです。 19 | 20 | - **設計**: コードはうまく設計され、そのシステムにとって適切か？ 21 | - **機能性**: コードは作成者の意図通りに動作するか？ユーザーにとってコードの挙動は適切か？ 22 | - **複雑さ**: コードはもっとシンプルにできるか？コードを作成した開発者があとになってもう一度そのコードに触れたとき、理解しやすく使いやすいか？ 23 | - **テスト**: そのコードには、正確で、うまく設計され、自動化されたテストがあるか？ 24 | - **命名**: 変数名、クラス名、メソッド名などに明解な名前を選んだか？ 25 | - **コメント**: コメントは明解で有益か？ 26 | - **スタイル**: コードは[スタイルガイド](http://google.github.io/styleguide/)に準拠しているか？ 27 | - **ドキュメント**: 関連するドキュメントも更新してあるか？ 28 | 29 | 詳細は**[コードレビューの仕方](reviewer/)**を確認してください。 30 | 31 | ### 最高のレビュアーを選ぶ {#best_reviewers} 32 | 33 | 一般的に、レビュアーを探すとなれば合理的な時間内でレビューに反応してくれる**最高の**レビュアーを見つけたいと思うでしょう。 34 | 35 | 最高のレビュアーとは、あなたが書いたコードにすみずみまで正確なレビューをしてくれる人です。 36 | 多くの場合、最高のレビュアーはコードの所有者です。OWNERS ファイルに記載されていることもありますが、そうでないこともあります。 37 | ときには CL の変更箇所をいくつかに分けて、それぞれ別の人にレビューをお願いするのが相応しい場合もあります。 38 | 39 | 理想的なレビュアーを見つけたとしても彼らが忙しくてレビューできないこともあります。そういうときでも少なくとも彼らを変更の CC に割り当てるべきです。 40 | 41 | ### 対面でのレビュー {#in_person} 42 | 43 | 適切なコードレビューをする資格のある人とペアプログラミングで書いたコードは、レビュー済みとみなせます。 44 | 45 | また、対面でコードレビューを受けることもできます。レビュアーが質問をし、コードの作成者が質問に答えるという形です。 46 | 47 | ## 参考 {#seealso} 48 | 49 | - [コードレビューの仕方](reviewer/): コードレビュアーのための詳細なガイド 50 | - [CL 作成者のガイド](developer/): CL がレビューを受けている開発者のための詳細なガイド 51 | -------------------------------------------------------------------------------- /ja/review/reviewer/comments.md: -------------------------------------------------------------------------------- 1 | # レビューコメントの書き方 2 | 3 | ## 要約 4 | 5 | - コメントは丁重に 6 | - 理由を説明してください 7 | - 問題の指摘に加えて明確な方向性を示すことと、開発者本人に決定を委ねることをバランス良く行ってください 8 | - 複雑なコードを見つけたらそれを説明してもらうだけで終わらせず、コードをシンプルにしてもらうとかコードにコメントを追加するよう開発者に勧めてください 9 | 10 | ## 礼儀正しさ 11 | 12 | 一般論として、あなたがレビューしているコードの開発者にコメントを送るとき、明確で有益な内容であることもちろん大切ですが、礼儀正しく敬意を払った書き方であることも大切です。 13 | それを実践する一つの方法は、必ず**コード**についてコメントし、**開発者本人**についてコメントしないよう心がけることです。 14 | この慣例に杓子定規に従う必要はありませんが、相手を傷つけたり怒らせたりするかもしれない繊細な内容を書くときには必ずそうするようにしてください。 15 | 以下はその例です。 16 | 17 | 悪い例「並行処理にしても明らかにメリットがないのに、どうして**あなたは**スレッドを使ったのですか？」 18 | 19 | 良い例「見たところ、ここで使った並行処理モデルは実際にはパフォーマンス上のメリットがないまま、ただシステムを複雑にしています。パフォーマンス上のメリットがないので、複数スレッドを使わずにシングルスレッドのコードにするのが最善です」 20 | 21 | ## 「なぜ」を説明する {#why} 22 | 23 | 上の「良い例」でひとつお気づきでしょうが、あなたが書いているコメントの「理由」を開発者が理解することは有益です。 24 | レビューコメントに必ずこの情報を含める必要があるかというと、そうではありませんが、それが適切な場合があります。 25 | そういうときには、コメントの意図についてもう少し詳しく説明したり、あなたが参考にしているベストプラクティスを教えたり、あなたの提案がどのようにコードの健康状態を良くするのかを解説したりしてください。 26 | 27 | ## 指示を与える {#guidance} 28 | 29 | **CL を修正するのは一般的に開発者の責任であって、レビュアーの責任ではありません。**ソリューションの詳細な設計をしたり開発者の代わりのコードを書いたりする仕事はレビュアーに求められていません。 30 | 31 | とはいえ、レビュアーは手助けしないでただ突き放せばよいということではありません。 32 | 一般にレビュアーは、問題を指摘することと指示を直接与えることを適度にバランス良く行うべきです。 33 | 問題を指摘して決定を開発者本人に任せることは、しばしば開発者が自分で学ぶ機会になりますし、コードレビューが楽になります。 34 | また、開発者はレビュアーよりもコードを間近で見ているので、開発者に任せるほうが良いソリューションになることもあります。 35 | 36 | その一方で、直接的な指示や提案や、ときにはコードを見せることがさらに有益になる場合もあります。 37 | コードレビューの主要な目的は CL の品質をできる限り良くすることです。 38 | 第二の目的は、開発者のスキルを向上させ、長期的にレビューを不要にすることです。 39 | 40 | ## 説明を受け入れる {#explanations} 41 | 42 | あなたが理解できないコードを開発者に説明してもらうのは、多くの場合、**コードをもっと明確に書き直してもらう**ほうが良い結果になります。 43 | ときには、複雑すぎるコードを説明してもらうだけでなく、コードにコメントを追加するのも適切な応答になります。 44 | 45 | **コードレビューツールの中に説明を書き残しても、将来そのコードを読む人にとって役に立ちません。**ツールにコメントを残すのが受け入れられるケースは、限られた状況だけです。たとえば、あなたがあまり詳しくない分野のレビューをしていて、通常そのコードを読む開発者はすでによく知っているような情報を説明してもらうときには、ツールにコメントを残せば十分です。 46 | 47 | 次: [コードレビュー中の取り下げに対応する](pushback.md) 48 | -------------------------------------------------------------------------------- /ja/review/reviewer/index.md: -------------------------------------------------------------------------------- 1 | # コードレビューの仕方 2 | 3 | このセクションでは、長年の経験に基づいて、コードレビューをする最良の方法に関するいろいろな推奨事項を説明しています。 4 | 各ページをひとまとめにすると一つの完全なドキュメントになりますが、便宜上、多くのセクションに分割しています。 5 | 全部を読む必要はありませんが、多数の感想によれば、ドキュメントを通読するのが個人としてもチームとしても非常に有益です。 6 | 7 | - [コードレビューの基準](standard.md) 8 | - [コードレビューの観点](looking-for.md) 9 | - [レビューで CL を閲覧する](navigate.md) 10 | - [コードレビューのスピード](speed.md) 11 | - [コードレビューコメントの書き方](comments.md) 12 | - [コードレビュー中の取り下げに対応する](pushback.md) 13 | 14 | [CL 作成者のガイド](../developer/)も参考にしてください。こちらは CL をコードレビューしてもらう側の開発者のための詳細なガイドです。 15 | -------------------------------------------------------------------------------- /ja/review/reviewer/looking-for.md: -------------------------------------------------------------------------------- 1 | # コードレビューの観点 2 | 3 | （注）以下のポイントを検討する際にはつねに[コードレビューの基準](standard.md)を忘れないでください。 4 | 5 | ## 設計 6 | 7 | レビューで確認すべき最も大切なことは、CL の全体的な設計です。 8 | CL のコードの各部分は相互にきちんと連携するでしょうか？この変更はコードベースに属するものでしょうか、それともあるライブラリに属するものでしょうか？システムの他の部分とうまく統合するでしょうか？この機能を追加するタイミングは今がふさわしいでしょうか？ 9 | 10 | ## 機能性 11 | 12 | この CL は開発者の意図通りに動作しますか？開発者の意図はこのコードのユーザーにとって適切でしょうか？「ユーザー」とは普通、エンドユーザー（その変更によって影響を受ける場合）と開発者（将来このコードを「使う」必要のある人）の両方を指します。 13 | 14 | 通常、CL がコードレビューに至るまでには、コードが正しく動作することを開発者が十分にテストしていると期待できます。 15 | それでもレビュアーはエッジケースを想定する、並行処理の問題を探す、ユーザーになりきって考えるなど、コードを読むだけではわからない不具合がないかを確認してください。 16 | 17 | 必要に応じて CL を検証しても**構いません**。特に、**UI の変更**といった、ユーザーに影響する変更があるときには、レビュアーが CL の動作を確認するべき最も重要な機会です。 18 | 変更がユーザーにどのような影響を与えるかはコードを読むだけではわかりにくいものです。 19 | そのような変更に対して、CL の変更を反映して自分で動作確認するのが難しければ、開発者にその機能のデモを依頼することもできます。 20 | 21 | また別のケースですが、コードレビュー中に機能について熟慮が特に求められるのは、CL にある種の**並行プログラミング**が行われていて、理論的にデッドロックや競合状態を引き起こす可能性がある場合です。 22 | こういう問題はコードを実行するだけでは不具合の発見が難しいため、通常、コード全体を見て問題が発生していないことを注意深く確認する人（開発者とレビュアーの両方）が必要です。 23 | （なお、これこそがやはり、競合状態やデッドロックが発生しうるところで並行処理モデルを採用すべきでない十分な理由です。コードレビューを行うにしてもコードを理解するにしても非常に複雑になりうるからです。） 24 | 25 | ## 複雑性 26 | 27 | CL が必要以上に複雑になっていないでしょうか？ CL のあらゆるレベルで確認してください。 28 | 一行一行は複雑すぎないでしょうか？関数は複雑すぎないでしょうか？クラスは複雑すぎないでしょうか？ 29 | 「複雑すぎる」とは普通、**「コードを読んですぐに理解できない」**という意味です。 30 | あるいは、**「開発者がこのコードを呼び出したり修正したりしようとするときに不具合を生み出す可能性がある」**という意味でもあります。 31 | 32 | あるタイプの複雑性は、**オーバーエンジニアリング**です。開発者が必要以上にコードを一般化していたり、現在のシステムにとってまだ必要のない機能を盛り込んでいたりするということです。 33 | レビュアーはオーバーエンジニアリングを特に警戒すべきです。 34 | 開発者には、**現在**解決する必要のある既知の問題に取り組むべきであって、将来解決する必要が出てくる**かもしれない**推測に基づいた問題には目を向けないよう勧めてください。 35 | 将来の問題はそれが発生してから取り組めばよいのです。問題が発生すれば、この物理的な宇宙の中でその実際の形と要件を知ることができます。 36 | 37 | ## テスト 38 | 39 | 変更に適したユニットテスト、結合テスト、E2E テストを依頼してください。 40 | 一般に、テストはプロダクションコードと同じ CL に追加してください。 41 | 例外は、CL が[緊急事態](../emergencies.md)に対処している場合です。 42 | 43 | CL の中のテストが正確で、適切で、有用であることを確認してください。 44 | テストがテストコード自体をテストすることはありませんし、テストのためのテストコードを書くこともめったにありません。テストの有効性は人間が確認しなければなりません。 45 | 46 | コードが壊れているときにテストはきちんと失敗するでしょうか？ 47 | そのテストの下でコードを変更すると、テストが誤検知を起こさないでしょうか？ 48 | 各テストはシンプルで有用なアサーションを使っているでしょうか？ 49 | テストは異なるテストメソッドごとに適切に分割されているでしょうか？ 50 | 51 | テストもまた保守すべきコードであることを覚えていてください。 52 | メインのバイナリに含まれないからといって、テストが複雑になるのを許容しないでください。 53 | 54 | ## 命名 55 | 56 | 開発者はあらゆるものに適切な名前を与えているでしょうか？ 57 | 適切な名前とは、それが何であるか／何をするかを伝えるのに十分に長く、しかし読むのに困難を覚えないほど短いものです。 58 | 59 | ## コメント 60 | 61 | 開発者はわかりやすい英語で明確なコメントを書きましたか？ 62 | すべてのコメントは実際に必要でしょうか？ 63 | コメントは普通、あるコードが**「なぜ」**存在するのかを説明するのに役立ちますが、コードが**「何」**をしているのかを説明すべきではありません。 64 | コードがそれ自身を説明するほど明確でないのなら、コードをもっとシンプルにすべきです。 65 | 例外はあります（たとえば正規表現や複雑なアルゴリズムでは何をしているのかを説明するコメントは非常に有益です）が、ほとんどの場合、コメントは決定の背後にある理由といった、コード自体が語ることのできない情報を伝えるために書きます。 66 | 67 | CL の前にその箇所にあったコメントに注目するのが有益であることもあります。 68 | 今となっては削除すべき TODO があるかもしれませんし、この変更を行うべきではないと助言するコメントなどがあるかもしれません。 69 | 70 | なお、コメントはクラス、モジュール、関数の**ドキュメンテーション**とは違います。ドキュメンテーションコメントはコードの目的や、使い方や、使われたときのふるまいを記述するものです。 71 | 72 | ## スタイル 73 | 74 | Google には[スタイルガイド](http://google.github.io/styleguide/)があります。メジャーな言語に関してはすべて、マイナーな言語でも多くはスタイルガイドが揃っています。 75 | CL が適切なスタイルガイドを従っているかを確認してください。 76 | 77 | スタイルガイドに記載のないスタイルの改善をしたい場合、コメントに「Nit:」というプレフィックスを付けて、それが細かい指摘 (nitpick) であることを開発者に知らせるのがよいでしょう。そうすると、コードを修正してほしいが強制ではないということが伝わります。 78 | 個人的なスタイルの好みで CL の提出をブロックしないでください。 79 | 80 | CL の作成者はスタイル上の大きな変更を他の変更に混ぜないようにしてください。 81 | それをすると CL で何が変更されているのかを見るのが難しくなるばかりか、マージ後にロールバックするのはもっと大変ですし、さらに他の問題も引き起こします。 82 | たとえば、作成者がファイル全体を再フォーマットしたいと思ったら、再フォーマットだけを一つの CL として提出し、その後で機能的な変更を別の CL として提出するようにしてください。 83 | 84 | ## ドキュメンテーション 85 | 86 | CL がコードのビルド、テスト、相互連携、リリースのやり方を変更する場合、それに関連するドキュメンテーションも更新しているかを確認してください。 87 | 関連するドキュメンテーションには、README、g3doc ページ、自動生成されたリファレンスドキュメントなどがあります。 88 | CL がコードを削除あるいは非推奨にしたら、ドキュメンテーションも削除するべきかどうか検討してください。 89 | ドキュメンテーションが存在しなければ、作成するように依頼してください。 90 | 91 | ## 一行ずつ {#every_line} 92 | 93 | レビューをアサインされたらコードを**一行ずつ**見てください。 94 | データファイル、自動生成されたコード、巨大なデータ構造などはざっと見れば済むこともありますが、人間の書いたクラス、関数、コードブロックなどはそうもいきません。 95 | コードの中に書かれているものが正しいと決めてかからず、じっくり読んでください。 96 | 明らかに他のコードよりも精密に調べるに値するコードもあります—そうすべきかどうかはレビュアーが自分で判断しなければなりません—が、少なくとも全コードが何をしているかを確実に**理解**するようにしてください。 97 | 98 | コードが読みにくく、そのことがレビューを遅らせているなら、レビューをいったん置いて開発者に知らせ、コードを明確にしてくれるのを待ちましょう。 99 | Google には優秀なソフトウェアエンジニアが雇われていますし、あなたはその一人です。 100 | あなたがコードを理解できないのなら、他の開発者もきっと理解できません。 101 | ですから、開発者にコードを明確にするよう依頼するのは、未来の開発者のためにこのコードを理解しやすくする手助けでもあります。 102 | 103 | コードを理解できてもレビューのある部分で自分にはレビューする資格がないと感じる場合、その CL について他に適切なレビュアーがいることを忘れないでください。 104 | 特に、セキュリティ、並行処理、アクセシビリティ、インターナショナライゼーションといった複雑な問題に関しては適任者がいます。 105 | 106 | ## コンテキスト 107 | 108 | CL を広いコンテキストの中に置いて眺めると有意義なことがよくあります。 109 | 普通コードレビューツールは変更のあった箇所の周りを数行ほど表示するだけです。 110 | 変更がうまく機能することを確認するためにファイル全体を見なければならないときもあります。 111 | たとえば、追加された行が 4 行だけだったとしても、ファイル全体を眺めたらそれが 50 行に及ぶメソッドの中に書かれていることがわかり、メソッドを分割する必要があると判明することもあります。 112 | 113 | CL をシステム全体のコンテキストの中に置いて考えてみることも有益です。 114 | この CL はシステムのコードの健康状態を改善しているでしょうか、それともシステム全体を複雑にし、テスト不足な状態にしているでしょうか？ 115 | **コードの健康状態を悪化させる CL を受け入れないでください。** 116 | ほとんどのシステムは小さな変更が積み重なってだんだんと複雑化します。 117 | だからこそ、新たな変更があったときに小さな複雑性でも混入させないようにするのが大切です。 118 | 119 | ## 良いこと {#good_things} 120 | 121 | CL の中に素晴らしいものを見つけたら、開発者に教えてあげてください。特に、あなたのレビューコメントの一つに取り組んで素晴らしくやり遂げたらそうしてください。 122 | コードレビューは間違いにばかり目が行きがちですが、良い実践に対しての励ましや感謝の言葉も伝えるべきです。 123 | メンタリングの観点では、開発者が正しいこと行ったときにそれを伝えるほうが、間違いを指摘するよりもずっと価値がある場合があります。 124 | 125 | ## 要約 126 | 127 | コードレビューをする際には、次のことを確認してください。 128 | 129 | - コードがうまく設計されている 130 | - 機能性がコードのユーザーにとって適切である 131 | - UI の変更がある場合、よく考えられていて見た目も適切である 132 | - 並行処理がある場合、安全に行われている 133 | - コードが必要以上に複雑でない 134 | - 開発者は将来必要になる**かもしれない**ものではなく、現在必要だとわかっているものを実装している 135 | - コードには適切なユニットテストがある 136 | - テストがうまく設計されている 137 | - 開発者はあらゆるものに明確な名前を使った 138 | - コメントは明確で有意義なもので、**「何」**ではなく**「なぜ」**を説明している 139 | - コードは適切にドキュメント化されている（一般的には g3doc で） 140 | - コードはスタイルガイドに準拠している 141 | 142 | レビューを依頼されたコードを**一行ずつ**レビューすること、**コンテキスト**を確認すること、**コードの健康状態を改善**しているかを見極めること、開発者が**良いこと**をしたらそれを褒めることを忘れずに。 143 | 144 | 次: [レビューで CL を閲覧する](navigate.md) 145 | -------------------------------------------------------------------------------- /ja/review/reviewer/navigate.md: -------------------------------------------------------------------------------- 1 | # レビューで CL を閲覧する 2 | 3 | ## 要約 4 | 5 | 前節で[コードレビューの観点](looking-for.md)を学びましたが、では複数ファイルにまたがった変更をレビューする最も効果的な方法は何でしょうか？ 6 | 7 | 1. 変更はうまく機能するでしょうか？適切な[ディスクリプション](../developer/cl-descriptions.md)はあるでしょうか？ 8 | 2. いちばん重要な変更を最初に確認してください。それは全体としてうまく設計されているでしょうか？ 9 | 3. CL の残りの部分を適切な順序で見てください。 10 | 11 | ## ステップ 1: 変更を広く眺める {#step_one} 12 | 13 | [CL のディスクリプション](../developer/cl-descriptions.md)と CL が大まかに何をしているかを確認してください。 14 | この変更は機能しているでしょうか？ 15 | そもそもこの変更が行ってはならないものであれば、変更すべきでない理由を添えてすぐに返信してください。 16 | そのように変更を却下する場合、代わりに何をすべきかを開発者に提案するのも良い考えです。 17 | 18 | たとえば、次のように伝えることができます。「これに関して良い仕事をしてくださっているように思えます。ありがとう！ですが、実はあなたがここで修正した FooWidget システムは削除する方向で進めているため、今のところ新しい修正をしたくないのです。代わりに新しい BarWidget クラスをリファクタリングしていただくのはどうでしょうか？」 19 | 20 | 注意していただきたいのですが、レビュアーは現在の CL を却下して代わりの提案をしただけではなくて、それを礼儀正しく伝えました。 21 | このような礼儀正しさは重要です。私達は意見が一致しないときでも開発者として互いを尊重し合うということを示したいからです。 22 | 23 | 変更してほしくない部分を変更する CL がいくつも送られる場合、 24 | チームの開発プロセスや外部のコントリビューター向けに投稿されたプロセスを再検討してください。 25 | CL が書かれる前にもっとコミュニケーションが必要です。 26 | 人々が 1 トンもの仕事をしてその後で破棄や大部分の書き直しを迫られるよりは、事前に「ノー」と言えるほうが良いでしょう。 27 | 28 | ## ステップ 2: CL の主要部分を調べる {#step_two} 29 | 30 | この CL の「メイン」の部分になっているファイル（1 ファイルとは限りません）を見つけてください。 31 | よくあるのは、ロジック上の変更が最も多いファイルが一つあり、それが CL の主要部分となる場合です。 32 | これが CL の別の小さな部分にコンテキストを提供していて、それによってコードレビューが概してスムーズになります。 33 | CL があまりに巨大でどの部分が主要部分なのか判別できなければ、開発者にどこを最初に見るべきか質問してもよいですし、あるいは [CL を複数の CL に分割する](../developer/small-cls.md)ように依頼してください。 34 | 35 | CL の主要部分に設計上の重大な問題が見つかれば、すぐにコメントを残してください。 36 | CL の残りの部分をレビューする時間があってもコメントを送るのが先です。 37 | 実際、CL の残りの部分をレビューしても時間の無駄になるかもしれません。設計上の問題が重大なものであれば、レビュー対象の他のコードは消されることになり、見ても見なくても関係なくなるからです。 38 | 39 | 設計上の重大な問題に関するコメントをただちに送ることが大切な理由は二つあります。 40 | 41 | - 開発者は CL を投稿すると、レビューを待ちながらその CL をベースに新しい作業をすぐに始めることがよくあります。 42 | レビュー中の CL に設計上の重大な問題があると、開発者は次の CL もやり直さなければならなくなります。 43 | 開発者が問題含みの設計の上にさらに仕事を積み上げてしまう前に引き止めたいものです。 44 | - 大きな設計の変更は小さな変更よりも時間がかかります。 45 | 開発者にはたいてい納期がありますが、納期を守りつつコードベースのコードの品質を保つには、CL のやり直しが重大なものであるほど、できるだけ早くやり直しに着手する必要があります。 46 | 47 | ## ステップ 3: CL の残りを適切な順序で見る {#step_three} 48 | 49 | 全体として CL に設計上の重大な問題がないことが確認できたら、次は全ファイルを一通り見て、論理的な順序を理解するようにしてください。またその際に、レビューもれのファイルがないように気をつけてください。 50 | 主要なファイルを確認し終えたら、普通はコードレビューツールが表示してくれる順序で各ファイルを調べるのがいちばん簡単です。 51 | 主要なコードを読む前にテストをまず読むのが効果的な場合もあります。 52 | そうするとこの変更が何をしようとしているのかイメージがつくからです。 53 | 54 | 次: [コードレビューのスピード](speed.md) 55 | -------------------------------------------------------------------------------- /ja/review/reviewer/pushback.md: -------------------------------------------------------------------------------- 1 | # コードレビュー中の取り下げに対応する 2 | 3 | 開発者がコードレビュー中に取り下げることがあります。開発者があなたの提案に同意できないこともありますし、あなたのレビューが厳格すぎるために開発者が不満を抱いてそうすることもあります。 4 | 5 | ## 正しいのは誰か？ {#who_is_right} 6 | 7 | 開発者があなたの提案に同意できないとき、最初に少し考慮していただきたいのは、開発者のほうが正しいのではないかということです。 8 | よくあることですが、開発者はあなたよりもコードを間近で見ているため、ある側面では開発者のほうが優れた洞察を持っていることもあります。 9 | 開発者の議論は筋が通っているでしょうか？コードの健康状態という視点から理にかなっているでしょうか？ 10 | そうであれば、開発者が正しいということを認め、問題を水に流しましょう。 11 | 12 | しかしながら、いつでも開発者が正しいとは限りません。その場合、レビュアーはどうして自分の提案が正しいと思うのかを踏み込んで説明しましょう。 13 | まず開発者の応答に理解を示し、それから変更が必要な理由を付け加えるのが良い説明です。 14 | 15 | 特に、レビュアーがコードの健康状態を良くする提案をしていると思われる場合には、その変更によってさらに作業が発生するもののそれに見合うだけコードの品質が改善すると見込まれれば、粘り強く変更を勧めるべきです。 16 | **コードの健康状態の改善は、スモールステップで行われます。** 17 | 18 | 提案がきちんと理解してもらえるまで何ラウンドか説明しなければならないときもありますが、いつも[丁重](comments.md#courtesy)に説明するのを忘れず、開発者の言葉にきちんと**耳を傾けた**上でただ**同意**できないだけなのだということを知らせてください。 19 | 20 | ## 人を悩ませる開発者 {#upsetting_developers} 21 | 22 | レビュアーが改善を要求すると開発者が傷つくのではないかとレビュアーが思い込んでいる場合があります。確かに開発者が傷つくこともありますが、普通はそれは一時的なことで、時が経つとコードの品質改善に協力してくれたことに深く感謝するようになるものです。 23 | [丁重](comments.md#courtesy)なコメントを心がけていれば、実際、開発者は傷ついたりしません。そういった心配はレビュアーの杞憂です。 24 | 傷つくことがあるとすれば、コードの品質改善の要求よりも[コメントの書き方](comments.md#courtesy)のほうに原因があるものです。 25 | 26 | ## あとで片付ける {#later} 27 | 28 | CL 取り下げのよくある理由は、（もっともなことですが）開発者が仕事を完了させたいからです。この CL を取り入れてもらうために何度もレビューのラウンドを重ねたくないのです。そのため、開発者はこう言います。あとで別の CL でその問題を片付けるから、**この** CL については今は LGTM してほしい、と。 29 | きちんと有言実行し、問題を解決するフォローアップの CL をすぐに書いてくれる開発者もいます。けれども、経験則が示すところによると、開発者が最初の CL を書いてから時間が経てば経つほど、その問題を片付ける可能性は低くなります。 30 | 事実、開発者が現在の CL の**直後に**問題を片付けるのでなければ、その機会は完全に消失します。こうなるのは開発者が無責任だからではなく、開発者がたくさんの仕事を抱えていて、他の仕事が押し流されて問題を片付けるのを忘れてしまったり時間を取れなくなったりするからです。 31 | ですから、最良の選択肢は普通、CL がコードベースに取り込まれて「完了 (done)」する前に、開発者に**今**片付けてもらうことです。「あとで片付ける」を許容するとコードベースは悪化します。 32 | 33 | CL が複雑さを新たに持ち込む場合、[緊急事態](../emergencies.md)でない限り、それが取り込まれる前にきちんと問題を片付ける必要があります。CL が周辺の問題を顕在化しているのに開発者がすぐにその問題に取り組めないときには、問題解決のためにバグを整理保存し、忘れないように自身をアサインしておきます。コードの直すべき箇所に任意で TODO コメントを入れることもできます。 34 | 35 | ## 厳格さに関するよくある不満 {#strictness} 36 | 37 | 以前はゆるいコードレビューをしていた人が急に厳格なレビューをするようになると、開発者があからさまに不満を言うようになることがあります。コードレビューの[スピード](speed.md)を改善すると、そうした不満は解消されることが多いです。 38 | 39 | ときには数カ月間にわたってこうした不満がくすぶり続けることもありますが、厳格なレビュープロセスによってコードの品質が向上しているのが目に見えてわかるようになるにつれて、厳格なコードレビューの価値を見直すようになります。それどころか、厳格なレビューによって付加された価値にちょっとしたきっかけで気づくようになると、最もあからさまに反対していた開発者が、最も熱心な支持者になることさえあります。 40 | 41 | ## 意見の対立の解消 {#conflicts} 42 | 43 | 上記の原則に従ってレビューした結果、それでもレビュアーと開発者の間で解決できない意見の対立が生じた場合、対立を解消するためのガイドラインおよび原則として[コードレビューの基準](standard.md)を参考にしてください。 44 | -------------------------------------------------------------------------------- /ja/review/reviewer/speed.md: -------------------------------------------------------------------------------- 1 | # コードレビューのスピード 2 | 3 | ## なぜコードレビューは素早く行うべきか？ {#why} 4 | 5 | **Google では開発者のチームが協力してプロダクトを高速に開発するために最適化しており**、開発者個人がコードを高速に書くための最適化はしません。 6 | 開発者個人のスピードは確かに重要ですが、チーム全体のスピードと比べると**同等の**重要性があるわけではありません。 7 | 8 | コードレビューが遅滞するとさまざまなことが起こります。 9 | 10 | - **チーム全体の開発速度が減少します。**もちろん、レビューに素早く反応しなくても個人としては他の仕事を終わらせられます。 11 | けれども、チームの他のメンバーが書いた新機能や不具合修正は、CL がレビュー待ち、再レビュー待ちになると何日も何週間も遅れることになります。 12 | - **開発者がコードレビューのプロセスに不満を持ち始めます。** 13 | レビュアーが数日おきにしか返信しないのに毎回 CL への大きな変更が要求されると、開発者はストレスをためるし開発が困難になります。 14 | よくあることですが、このようなときに表現される不満は、レビュアーが「厳しすぎる」というものです。 15 | 本質的には**同じ**変更（実際にコードの健康状態を良くする変更）でも開発者の更新に応じてレビュアーが毎回**素早く**返信すれば、このような不満は薄れます。 16 | **コードレビューに関する不満はたいていの場合、プロセスをテンポ良く進めるだけで解消します。** 17 | - **コードの健康状態が悪い影響を受けます。** 18 | レビューが遅いと、最高の出来映えといえないような CL でもとにかく提出してしまってよいという雰囲気が開発者の間に広がります。 19 | また、レビューの遅れはコードをきれいにしたり、リファクタリングしたり、既存の CL をさらに改善したりする意欲をそぎます。 20 | 21 | ## コードレビューはどれほど急ぐべきか？ {#fast} 22 | 23 | あるタスクに集中的に取り組んでいる最中でなければ、**コードレビューの依頼が来たらすぐに着手してください。** 24 | 25 | コードレビューのリクエストに返信するまでの**最長の時間は一営業日**です（つまり遅くとも翌朝一番に返信すべきです）。 26 | 27 | このガイドラインに従うと、典型的な CL は（必要なら）一日以内に複数ラウンドに渡ってレビューが行われることになります。 28 | 29 | ## スピード vs 割り込み {#interruption} 30 | 31 | チームの速度よりも個人の速度を尊重したほうが効率が良い場合があります。 32 | **コードを書くような集中的に取り組むべきタスク**の最中には、自分のタスクを中断してコードレビューしてはいけません。研究結果によれば、開発者が割り込み作業のあとでスムーズな開発フローに戻るには長い時間がかかることがあります。 33 | そのため、コーディングの最中に中断すると、他の開発者がコードレビューを多少待つよりも結果的に**余計な**コストがかかります。 34 | 35 | それよりは仕事のブレークポイントを待ってからレビューのリクエストに返信しましょう。 36 | たとえば今のコーディングが完了したときや、ランチの後や、ミーティングから帰ったとき、マイクロキッチンから戻ったときなどです。 37 | 38 | ## 素早い応答 {#responses} 39 | 40 | コードレビューのスピードについて話すとき、私達の関心は**応答**時間の長さであり、レビュー全体が完了して提出されるまでの時間の長さではありません。 41 | 理想的にはプロセス全体も短時間で行うべきですが、** _個々の応答_ を素早く行うことのほうが、プロセス全体を短時間で終えることよりも遥かに重要です。** 42 | 43 | たとえレビュー全体の**プロセス**に長い時間がかかってもレビュアーから素早く応答がもらえていれば、開発者が「遅い」コードレビューに感じる不満を大きく軽減できます。 44 | 45 | あなたが非常に忙しくて CL のレビュー依頼をされても十分な時間が取れない場合、それでも素早く応答することはできます。いつ着手できるかを開発者に伝えたり、もっと短時間で応答できる他のレビュアーを紹介したり、[広い観点で見た初期段階のコメントを残したり](navigate.md)できます。（注：そういった返信をするとしてもコーディングを中断するべきではありません。仕事中にちょうどいいブレークポイントを見つけて返信してください。） 46 | 47 | **レビュアーが十分な時間を取って、「LGTM」が個人の感想でなく「このコードは[私達の基準](standard.md)を満たしている」という意味だと言えるくらいにレビューするのは大切なことです。**同時に、理想的には個々の応答は[素早く](#fast)返信すべきです。 48 | 49 | ## タイムゾーンをまたがるレビュー {#tz} 50 | 51 | タイムゾーンの違いを取り回すには、CL 作成者がいつオフィスに確実にいるかを確認するようにしてください。すでに家に帰ってしまったかもしれません。そのときには翌日に作成者がオフィスに戻る前にレビューを完了するように心がけてください。 52 | 53 | ## コメント付きの LGTM {#lgtm-with-comments} 54 | 55 | コードレビューのスピードを上げるために、レビュアーが CL に未解決のコメントを残しつつも LGTM / 承認を与えるというケースがあります。これは次のいずれかに当てはまる場合にそうするべきです。 56 | 57 | - 開発者がレビュアーの残したコメントに後で着実に取り組んでくれるとレビュアーが信頼できるとき 58 | - 先送りにした変更がさほど重要でなく、開発者本人が**必ずしも**行う必要のないとき 59 | 60 | これらのうちどちらがレビュアーの意図なのかをはっきりさせておかないと、曖昧な態度は開発者を混乱させます。 61 | 62 | コメント付きの LGTM が価値を発揮するのは、特に開発者とレビュアーが別々のタイムゾーンで仕事をしているときです。このやり方でレビューを進めないと、開発者は「LGTM / 承認」をもらうためだけに丸一日待たなければならなくなります。 63 | 64 | ## 大きな CL {#large} 65 | 66 | 送られてきたコードレビューがあまりに巨大で、じっくりレビューする時間を取れるか不安なときには、開発者にその CL を[小さな CL に分割する](../developer/small-cls.md)よう依頼するのがよくある対応策です。 67 | 一度にレビューするのが大変な一つの巨大な CL ではなく、それぞれが関連している小さな CL に分割するのです。 68 | これは開発者にとってみれば仕事が増えますが、普通の CL では不可能な作業でもなく、レビュアーにとっては非常に助かります。 69 | 70 | CL が小さな CL に分割**できない**場合、またさらにレビュアーがすぐにコード全体をレビューする時間が取れないとき、それでも少なくとも CL の全体的な設計に関してコメントを書き送り、開発者に改善を求めることができます。 71 | いつでも言えることですが、レビュアーとしてのゴールの一つは開発者を作業を滞らせないこと、あるいは次のアクションをすぐに起こせる状態にしておくことです。もちろんコードの健康状態を犠牲にしてはいけませんが。 72 | 73 | ## コードレビューを長期的に改善する {#time} 74 | 75 | あなたがこのガイドラインに準拠してコードレビューを厳密に行っていけば、全体的なコードレビューのプロセスが時間をかけてだんだんと速くなっていくのがわかるはずです。 76 | 開発者は健康的なコードを書くために何が必要かを学び、最初から質の高い CL を送るようになり、レビューに必要な時間はだんだんと減っていきます。 77 | レビュアーは素早く応答することを学び、レビュープロセスに無駄な遅延がなくなります。 78 | それでも、**[コードレビューの基準](standard.md)に妥協しないでください。スピードを上げてもコードの品質の改善に妥協しないでください。**長期的にみれば、レビューが短時間で終えられたからといって、それだけでひとかどの仕事をしたことにはなりませんから。 79 | 80 | ## 緊急事態 81 | 82 | [緊急事態](../emergencies.md)というものもあります。緊急事態の CL は**全**レビュープロセスを素早く終えなければなりませんし、品質に関するガイドラインは緩められます。 83 | けれども、どんな状況が緊急事態に該当するのか、逆にどんな状況が緊急事態に該当しないのかを判断するために[何が緊急事態か？](../emergencies.md#what)を確認してください。 84 | 85 | 次: [コードレビューのコメントの書き方](comments.md) 86 | -------------------------------------------------------------------------------- /ja/review/reviewer/standard.md: -------------------------------------------------------------------------------- 1 | # コードレビューの基準 2 | 3 | コードレビューの主な目的は、Google のコードベースにあるコードの全体的な健康状態を時間をかけて改善することです。 4 | コードレビューのすべてのツールとプロセスは、その目的のために設計されています。 5 | 6 | これを実現するには、さまざまなトレードオフのバランスを取る必要があります。 7 | 8 | まず第一に、開発者は自分のタスクを**進める**ことができなければなりません。 9 | コードベースに改善を提出できなければ、コードベースは改善しません。 10 | また、**どんな**変更に対してもレビュアーがいちいち難色を示して変更を取り入れずにいると、早晩、開発者は改善を行う意欲を失います。 11 | 12 | 一方、CL の品質を確認するのはレビュアーの義務です。CL を取り入れてコードベースのコードの全体的な健康状態 (code health) がだんだんと悪化するのは問題ですから、きちんと確認しなければなりません。 13 | これは骨の折れるやっかいな仕事になることがあります。 14 | というのも、多くの場合、コードの健康状態を悪化させる要因が積み重なり、コードベースの品質は徐々に下がります。 15 | 特に、チームが無視できない時間的制約に縛られていて、ゴールを達成するためにはショートカットをするしかないと感じているときには、コードベースの品質は下がりやすいものです。 16 | 17 | また、レビュアーにはレビュー中のコードに対して所有権と責任があります。 18 | レビュアーはコードベースの一貫性と保守可能性を維持し、[「コードレビューの観点」](looking-for.md)で言及されている事項を守りたいと考えています。 19 | 20 | こうして、私達はコードレビューに期待する基準として、次のルールを見出しました。 21 | 22 | **一般に、CL が完璧でなくても、その変更がシステムのコードの全体的な健康状態を改善すると確実にわかれば、レビュアーは CL を積極的に承認すべきである。** 23 | 24 | これはコードレビューの全ガイドラインで**最上位の**原則です。 25 | 26 | もちろん、制限はあります。たとえば、CL がレビュアーが望んでいない機能をシステムに追加している場合、うまくコードが設計されてるとしてもレビュアーは承認を拒否することができます。 27 | 28 | ここでのポイントは、「完璧な」コードといったものは存在しないということです—存在するのは**より良い**コードだけです。 29 | レビュアーは CL の承認を保留したままコードのすみずみまで磨きをかけることを要求すべきではありません。 30 | むしろ、前に進めるべきかどうかの必要性を、CL 作成者が提案している変更の重要性と比較して、バランスよく検討すべきです。 31 | レビュアーが追求すべきは、完璧さではなく**継続的な改善**です。 32 | CL が全体としてシステムの保守性、可読性、理解可能性を向上させるのなら、コードが「完璧」でないからといって数日も数週間も遅らせるべきではありません。 33 | 34 | レビュアーは何か改善できそうな点を見つけたら、コメントを残すのに躊躇する必要はありません。 35 | **いつでも**気軽にコメントを残すべきです。 36 | その際に、もし重要でない指摘であれば、「Nit: 」（あら探しや細かい指摘という意味）のようなプレフィックスを付けて、 37 | これはただ完全を期すための指摘なので無視してもらっても構わない、と CL 作成者に知らせると良いでしょう。 38 | 39 | （注）このドキュメントは、システムのコードの全体的な健康状態を**悪化**させるとわかりきっている CL を正当化しません。 40 | 唯一それが許されるケースは、[緊急事態](../emergencies.md)にあります。 41 | 42 | ## メンタリング 43 | 44 | コードレビューは、開発者に言語、フレームワーク、あるいはソフトウェア設計の一般的な原則に関して新しいことを教える重要な機会になります。 45 | 開発者が新しいことを学ぶヒントになるコメントは、いつでも歓迎されます。 46 | 知識の共有は、時間をかけてシステムのコードの健康状態を改善する試みの一部分です。 47 | 一点だけ頭に入れていただきたいのは、コメントが純粋に教育目的であって、このドキュメントで説明している基準を満たす上で重要でなければ、「Nit: 」などのプレフィックスを付けるか、この CL で作成者が解決する義務はないと付け加えてください。 48 | 49 | ## 原則 {#principles} 50 | 51 | - 技術的な事実とデータが個人的な意見と好みをくつがえす。 52 | 53 | - スタイルに関しては、[スタイルガイド](http://google.github.io/styleguide/)が絶対的な権威である。スタイルガイドの記載のない純粋なスタイルの選択（空白をどうするかなど）は個人の好みの問題である。スタイルはシステム内で一貫している必要がある。スタイルの選択に前例がなければ、CL 作成者のやり方を受けれるべきである。 54 | 55 | - ソフトウェア設計に関する論点はほとんどの場合、純粋なスタイルの問題でも個人的な好みの問題でもない。それは基本的な原則に基づいており、ただの個人的な意見によるのではなく、その原則に重点を置くべきである。有効な選択肢がいくつかある場合がある。複数の方法が同等に有効であると作成者が（データを示したり堅固な工学原理に基づいて説明したりして）証明できるとき、レビュアーは作成者の選好を受け入れるべきである。そうでない場合、選択はソフトウェア設計の標準的な原則によって決定される。 56 | 57 | - 他のルールが適用されない場合、システムのコードの全体的な健康状態を悪化させない限りは、レビュアーは CL 作成者に現在のコードベースとの一貫性を維持するよう求めることができる。 58 | 59 | ## 意見の対立の解消 {#conflicts} 60 | 61 | コードレビューで意見の対立があれば、最初のステップで必ず行うべきは、このドキュメントと[CL 作成者のガイド](../developer/)、またこの[レビュアーガイド](index.md)の他のドキュメントに基づいて、開発者とレビュアーの間でコンセンサスが得られるように調整することです。 62 | 63 | コンセンサスを得るのが特に難しいときには、レビュアーと作成者で対面でのミーティングやテレビ会議をもつほうが、コードレビューコメントのやり取りだけで対立を解消しようとするよりも効果がある場合があります。 64 | （対面でミーティングをするとしても、未来の読者のために CL のコメントにディスカッションの結果を記録するのを忘れないでください。） 65 | 66 | それでも状況が変わらないなら、通例では、巻き込む人を増やすのが解決する方法です。 67 | よくあるのがより広範にチーム内で議論することです。TL に検討してもらったり、コードのメンテナーに決定してもらうようお願いしたり、技術マネージャーに助力を求めたりできます。 68 | **作成者とレビュアーが合意に達することができないからといって、CL をそのまま放置しないでください。** 69 | 70 | 次: [コードレビューの観点](looking-for.md) 71 | -------------------------------------------------------------------------------- /locales/index.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: Google Engineering Practices Documentation 3 | ja: Google Engineering Practices Documentation (日本語訳) 4 | --- 5 | texts: 6 | en: >- 7 | Google has many generalized engineering practices that cover all languages and 8 | 9 | all projects. These documents represent our collective experience of various 10 | 11 | best practices that we have developed over time. It is possible that open source 12 | 13 | projects or other organizations would benefit from this knowledge, so we work to 14 | 15 | make it available publicly when possible. 16 | ja: >- 17 | Google には、全言語および全プロジェクトをカバーする広範なエンジニアリングの慣行があります。 18 | 19 | ここにあるドキュメントは私達が長年の経験からさまざまなベストプラクティスを蓄積してきたことを表しています。 20 | 21 | この知識がオープンソースプロジェクトや他の組織の利益になることを願って、私達は可能ならそれを誰にでも利用できるように公開します。 22 | --- 23 | texts: 24 | en: "Currently this contains the following documents:" 25 | ja: "現在、以下のドキュメントがあります。" 26 | --- 27 | texts: 28 | en: >- 29 | [Google's Code Review Guidelines](review/index.md), which are actually two 30 | separate sets of documents: 31 | ja: >- 32 | [Google コードレビューガイドライン](ja/review/index.md)。これは 2 つのドキュメントからなります。 33 | --- 34 | texts: 35 | en: "[The Code Reviewer's Guide](review/reviewer/index.md)" 36 | ja: "[コードレビュアーのガイド](ja/review/reviewer/index.md)" 37 | --- 38 | texts: 39 | en: "[The Change Author's Guide](review/developer/index.md)" 40 | ja: "[変更作成者のガイド](ja/review/developer/index.md)" 41 | --- 42 | texts: 43 | en: Terminology 44 | ja: 用語 45 | --- 46 | texts: 47 | en: >- 48 | There is some Google-internal terminology used in some of these documents, which 49 | 50 | we clarify here for external readers: 51 | ja: >- 52 | ここにあるドキュメントには、Google 内部で使われる用語があります。外部の読者のために意味を掲載しておきます。 53 | --- 54 | texts: 55 | en: >- 56 | **CL**: Stands for "changelist," which means one self-contained change that 57 | has been submitted to version control or which is undergoing code review. 58 | Other organizations often call this a "change" or a "patch." 59 | ja: >- 60 | **CL**: 「changelist」の略。一つの独立した変更を意味していて、バージョン管理に提出されたものや、まだコードレビュー中のものを指すこともあります。他組織では「変更」「パッチ」とよく呼ばれます。 61 | --- 62 | texts: 63 | en: >- 64 | **LGTM**: Means "Looks Good to Me." It is what a code reviewer says when 65 | approving a CL. 66 | ja: >- 67 | **LGTM**: 「Looks Good to Me」という意味。コードレビュアーが CL を承認するときに言う。 68 | --- 69 | texts: 70 | en: License 71 | ja: ライセンス 72 | --- 73 | texts: 74 | en: >- 75 | The documents in this project are licensed under the CC-By 3.0 License, which 76 | 77 | encourages you to share these documents. See 78 | 79 | https://creativecommons.org/licenses/by/3.0/ for more details. 80 | ja: このプロジェクトのドキュメントは CC-By 3.0 License の下にあります。ここにあるドキュメントをぜひシェアしてください。詳細は https://creativecommons.org/licenses/by/3.0/ をご覧ください。 81 | --- 82 | texts: 83 | en: Creative Commons License 84 | ja: __COPY__ 85 | -------------------------------------------------------------------------------- /locales/review/developer/cl-descriptions.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: Writing good CL descriptions 3 | ja: 適切な CL のディスクリプションを書く 4 | --- 5 | texts: 6 | en: >- 7 | A CL description is a public record of **what** change is being made and **why** 8 | 9 | it was made. It will become a permanent part of our version control history, and 10 | 11 | will possibly be read by hundreds of people other than your reviewers over the 12 | 13 | years. 14 | ja: CL のディスクリプションは**何**が変更され、**なぜ**変更されたのかを説明する公式記録です。この記録はバージョン管理の履歴に永続的に残され、長期にわたって読まれます。レビュアー以外にも数百人もの人が読むこともあります。 15 | --- 16 | texts: 17 | en: >- 18 | Future developers will search for your CL based on its description. Someone in 19 | 20 | the future might be looking for your change because of a faint memory of its 21 | 22 | relevance but without the specifics handy. If all the important information is 23 | 24 | in the code and not the description, it's going to be a lot harder for them to 25 | 26 | locate your CL. 27 | ja: 将来の開発者はあなたの CL をディスクリプションに基づいて検索します。将来の誰かがあなたの作成した変更を見つけようとして、詳細は忘れているけれどもその変更に関するおぼろげな記憶を頼りに検索するかもしれません。重要な情報がすべてコードにだけ書かれていてディスクリプションに記載されていないと、探している CL を見つけるのが非常に難しくなるでしょう。 28 | --- 29 | texts: 30 | en: First Line {#firstline} 31 | ja: 一行目 {#firstline} 32 | --- 33 | texts: 34 | en: Short summary of what is being done. 35 | ja: 何を行っているのかを短く要約する 36 | --- 37 | texts: 38 | en: Complete sentence, written as though it was an order. 39 | ja: 完全な文で、命令形で書く 40 | --- 41 | texts: 42 | en: Follow by empty line. 43 | ja: 次の行は空行にする 44 | --- 45 | texts: 46 | en: >- 47 | The **first line** of a CL description should be a short summary of 48 | 49 | *specifically* **what** *is being done by the CL*, followed by a blank line. 50 | 51 | This is what most future code searchers will see when they are browsing the 52 | 53 | version control history of a piece of code, so this first line should be 54 | 55 | informative enough that they don't have to read your CL or its whole description 56 | 57 | just to get a general idea of what your CL actually *did*. 58 | ja: CL の**一行目**には、その CL が**何**を行っているのかを明確に記した短い要約を書いてください。二行目は空行にしてください。将来コードを検索する人はコードのバージョン管理履歴を拾い読みするのにまずこの箇所を読むことになります。そのときにあなたの CL が何を**した**のか概要をつかむために CL のコードやディスクリプション全体を読まなくて済むように、一行目にしっかりと有益な情報を盛り込んでください。 59 | --- 60 | texts: 61 | en: >- 62 | By tradition, the first line of a CL description is a complete sentence, written 63 | 64 | as though it were an order (an imperative sentence). For example, say 65 | 66 | \"**Delete** the FizzBuzz RPC and **replace** it with the new system." instead 67 | 68 | of \"**Deleting** the FizzBuzz RPC and **replacing** it with the new system." 69 | 70 | You don't have to write the rest of the description as an imperative sentence, 71 | 72 | though. 73 | ja: 慣習的に、CL のディスクリプションの一行目は完全な文で、命令のように (命令形で) 書きます。たとえば、「**Deleting** the FizzBuzz RPC and **replacing** it with the new system.」と書くのではなく「**Delete** the FizzBuzz RPC and **replace** it with the new system.」と書きます。もっとも、ディスクリプションの他の部分まで命令形で書く必要はありません。 74 | --- 75 | texts: 76 | en: Body is Informative {#informative} 77 | ja: 主要部に有益な情報を盛り込む {#informative} 78 | --- 79 | texts: 80 | en: >- 81 | The rest of the description should be informative. It might include a brief 82 | 83 | description of the problem that's being solved, and why this is the best 84 | 85 | approach. If there are any shortcomings to the approach, they should be 86 | 87 | mentioned. If relevant, include background information such as bug numbers, 88 | 89 | benchmark results, and links to design documents. 90 | ja: 二行目以降のディスクリプションには有益な情報を盛り込んでください。解決されている問題に関する短い説明を書くこともありますし、なぜこれが最良の方法なのかを説明することもあります。その方法に欠陥があれば、その点にも言及してください。また関連があれば、バグチケットの番号やベンチマーク結果、設計ドキュメントのリンク等の背景も書いてください。 91 | --- 92 | texts: 93 | en: Even small CLs deserve a little attention to detail. Put the CL in context. 94 | ja: 小さな CL であっても詳細に書くよう心がける価値があります。CL をコンテキストの中に位置付けてください。 95 | --- 96 | texts: 97 | en: Bad CL Descriptions {#bad} 98 | ja: CL ディスクリプションの悪い例 {#bad} 99 | --- 100 | texts: 101 | en: >- 102 | "Fix bug" is an inadequate CL description. What bug? What did you do to fix it? 103 | 104 | Other similarly bad descriptions include: 105 | ja: 「Fix bug」とだけ書いた CL ディスクリプションは情報量不足です。どんなバグでしょうか？バグを修正するために何をしたのでしょうか？他にも悪いディスクリプションの例を以下に示します。 106 | --- 107 | texts: 108 | en: '"Fix build."' 109 | ja: __COPY__ 110 | --- 111 | texts: 112 | en: '"Add patch."' 113 | ja: __COPY__ 114 | --- 115 | texts: 116 | en: '"Moving code from A to B."' 117 | ja: __COPY__ 118 | --- 119 | texts: 120 | en: '"Phase 1."' 121 | ja: __COPY__ 122 | --- 123 | texts: 124 | en: '"Add convenience functions."' 125 | ja: __COPY__ 126 | --- 127 | texts: 128 | en: '"kill weird URLs."' 129 | ja: __COPY__ 130 | --- 131 | texts: 132 | en: >- 133 | Some of those are real CL descriptions. Their authors may believe they are 134 | 135 | providing useful information, but they are not serving the purpose of a CL 136 | 137 | description. 138 | ja: いくつかのものは実際にあった CL ディスクリプションです。作成者は有益な情報を提供しているつもりかもしれませんが、上の例は CL ディスクリプションの目的を果たせていません。 139 | --- 140 | texts: 141 | en: Good CL Descriptions {#good} 142 | ja: 適切な CL ディスクリプションの例 {#good} 143 | --- 144 | texts: 145 | en: Here are some examples of good descriptions. 146 | ja: 以下は適切なディスクリプションの例です。 147 | --- 148 | texts: 149 | en: Functionality change 150 | ja: 機能変更 151 | --- 152 | texts: 153 | en: "rpc: remove size limit on RPC server message freelist." 154 | ja: "rpc: RPC サーバーのメッセージフリーリストのサイズ制限を取り除く。(訳注: 英語では命令形)" 155 | --- 156 | texts: 157 | en: >- 158 | Servers like FizzBuzz have very large messages and would benefit from reuse. 159 | Make the freelist larger, and add a goroutine that frees the freelist entries 160 | slowly over time, so that idle servers eventually release all freelist 161 | entries. 162 | ja: "FizzBuzz のようなサーバーには巨大なメッセージがあり、再利用することでメリットがある。フリーリストを大きくし、徐々にフリーリストエントリーを解放する goroutine を追加することで、アイドリング中のサーバーが最終的にすべてのフリーリストエントリーを解放するようにした。" 163 | --- 164 | texts: 165 | en: >- 166 | The first few words describe what the CL actually does. The rest of the 167 | 168 | description talks about the problem being solved, why this is a good solution, 169 | 170 | and a bit more information about the specific implementation. 171 | ja: "最初の文で CL が実際に何をするのかを説明しています。以降のディスクリプションでは、解決される問題となぜこれが適切な解決なのか、また特定の実装に関する付加情報を記述しています。" 172 | --- 173 | texts: 174 | en: Refactoring 175 | ja: リファクタリング 176 | --- 177 | texts: 178 | en: Construct a Task with a TimeKeeper to use its TimeStr and Now methods. 179 | ja: "TimeStr と Now メソッドを使用するため Task を TimeKeeper と一緒に初期化する。(訳注: 英語では命令形)" 180 | --- 181 | texts: 182 | en: >- 183 | Add a Now method to Task, so the borglet() getter method can be removed (which 184 | was only used by OOMCandidate to call borglet's Now method). This replaces the 185 | methods on Borglet that delegate to a TimeKeeper. 186 | ja: Task に Now メソッドを追加することで、borglet() getter method を除去できるようにする (これは OOMCandidate が borglet の Now メソッドを呼び出すために使うだけだった)。これは TimeKeeper に委譲する Borglet のメソッドを置き換える。 187 | --- 188 | texts: 189 | en: >- 190 | Allowing Tasks to supply Now is a step toward eliminating the dependency on 191 | Borglet. Eventually, collaborators that depend on getting Now from the Task 192 | should be changed to use a TimeKeeper directly, but this has been an 193 | accommodation to refactoring in small steps. 194 | ja: Task に Now を与えられるようにするのは Borglet への依存をなくすための一ステップである。最終的には Task から Now を取得することに依存している部分は TimeKeeper を直接使うように変更すべきだが、これはスモールステップでリファクタリングするための調整である。 195 | --- 196 | texts: 197 | en: Continuing the long-range goal of refactoring the Borglet Hierarchy. 198 | ja: Borglet の階層構造をリファクタリングする長丁場のゴールに向けて引き続き作業する。 199 | --- 200 | texts: 201 | en: >- 202 | The first line describes what the CL does and how this is a change from the 203 | 204 | past. The rest of the description talks about the specific implementation, the 205 | 206 | context of the CL, that the solution isn't ideal, and possible future direction. 207 | 208 | It also explains *why* this change is being made. 209 | ja: >- 210 | 一行目は CL が何をするのかとどのような変更なのかを説明しています。以降のディスクリプションでは特定の実装と CL のコンテキストを説明しています。CL のソリューションは理想的ではないものの将来の方向性を示しています。またこの説明では**なぜ**この変更が行われるのかにも言及しています。 211 | --- 212 | texts: 213 | en: Small CL that needs some context 214 | ja: コンテキストの説明が必要な小さな CL 215 | --- 216 | texts: 217 | en: Create a Python3 build rule for status.py. 218 | ja: "status.py の Python3 ビルドルールを作成する (訳注: 英語では命令形)" 219 | --- 220 | texts: 221 | en: >- 222 | This allows consumers who are already using this as in Python3 to depend on a 223 | rule that is next to the original status build rule instead of somewhere in 224 | their own tree. It encourages new consumers to use Python3 if they can, 225 | instead of Python2, and significantly simplifies some automated build file 226 | refactoring tools being worked on currently. 227 | ja: これにより、Python3 ですでにそうしているようにこれを使用しているユーザーが自分の tree の中を探さなくても規定の status ビルドルールの隣のルールに依存できるようになる。そのことで新しいユーザーには可能なら Python2 ではなく Python3 を使用するよう促し、現在作業中の自動化されたビルドファイルのリファクタリングツールが有意に単純化される。 228 | --- 229 | texts: 230 | en: >- 231 | The first sentence describes what's actually being done. The rest of the 232 | 233 | description explains *why* the change is being made and gives the reviewer a lot 234 | 235 | of context. 236 | ja: 一文目は何が実際に行われているのかを説明しています。以降のディスクリプションでは**なぜ**その変更が行われるのかを説明し、レビュアーに十分なコンテキストを提供しています。 237 | --- 238 | texts: 239 | en: Review the description before submitting the CL 240 | ja: CL を提出する前にディスクリプションをレビューする 241 | --- 242 | texts: 243 | en: >- 244 | CLs can undergo significant change during review. It can be worthwhile to review 245 | 246 | a CL description before submitting the CL, to ensure that the description still 247 | 248 | reflects what the CL does. 249 | ja: CL はレビューの間、重要な変更を被ることがあります。CL を提出する前に CL ディスクリプションをレビューするのが有意義な場合があります。それはディスクリプションが CL の内容を正しく反映してることを確認するためです。 250 | --- 251 | texts: 252 | en: "Next: [Small CLs](small-cls.md)" 253 | ja: "次: [小さな CL](small-cls.md)" 254 | -------------------------------------------------------------------------------- /locales/review/developer/handling-comments.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: How to handle reviewer comments 3 | ja: レビューコメントの対応の仕方 4 | --- 5 | texts: 6 | en: >- 7 | When you've sent a CL out for review, it's likely that your reviewer will 8 | 9 | respond with several comments on your CL. Here are some useful things to know 10 | 11 | about handling reviewer comments. 12 | ja: >- 13 | CL をレビューに送ると、レビュアーが CL にいくつかのコメントを残してくれます。ここではレビュアーのコメントに対応するときに知っておくと有益なポイントを紹介します。 14 | --- 15 | texts: 16 | en: Don't Take it Personally {#personal} 17 | ja: 個人の人格へのコメントとして受け取らない {#personal} 18 | --- 19 | texts: 20 | en: >- 21 | The goal of review is to maintain the quality of our codebase and our products. 22 | 23 | When a reviewer provides a critique of your code, think of it as their attempt 24 | 25 | to help you, the codebase, and Google, rather than as a personal attack on you 26 | 27 | or your abilities. 28 | ja: >- 29 | レビューの目的は私達のコードベースと私達のプロダクトの品質を維持することです。レビュアーがあなたのコードに苦言を呈したら、それを個人攻撃とかあなたの能力をくさしているとか受け取らずに、レビュアーがあなたを手助けしようとしていると考えてみてください。レビュアーはコードベースを、また Google を良くしようとしているのです。 30 | --- 31 | texts: 32 | en: >- 33 | Sometimes reviewers feel frustrated and they express that frustration in their 34 | 35 | comments. This isn't a good practice for reviewers, but as a developer you 36 | 37 | should be prepared for this. Ask yourself, "What is the constructive thing that 38 | 39 | the reviewer is trying to communicate to me?" and then operate as though that's 40 | 41 | what they actually said. 42 | ja: >- 43 | ときにはレビュアーが苛立って、そのイライラをコメントに表現することもあります。これはレビュアーとして褒められた行いではありませんが、開発者としてはこうしたことへの心構えをしましょう。ご自分にこう問いかけてください。「レビュアーが私に伝えようとしている建設的な事柄は何だろう？」と。そして、それがレビュアーの真意だと捉えてください。 44 | --- 45 | texts: 46 | en: >- 47 | **Never respond in anger to code review comments.** That is a serious breach of 48 | 49 | professional etiquette that will live forever in the code review tool. If you 50 | 51 | are too angry or annoyed to respond kindly, then walk away from your computer 52 | 53 | for a while, or work on something else until you feel calm enough to reply 54 | 55 | politely. 56 | ja: >- 57 | **コードレビューコメントに対して怒りに任せて反応しないでください。**怒りに任せたコメントはプロとしての礼儀作法に違反しますし、それがコードレビューツールに永遠に残ることになります。もしあなたが怒りや苛立ちで丁重に応答できなくなっていれば、しばらく席を立って歩いたり他の作業に当たったりして、気持ちが落ち着いて丁重な応答ができるようになるのを待ってください。 58 | --- 59 | texts: 60 | en: >- 61 | In general, if a reviewer isn't providing feedback in a way that's constructive 62 | 63 | and polite, explain this to them in person. If you can't talk to them in person 64 | 65 | or on a video call, then send them a private email. Explain to them in a kind 66 | 67 | way what you don't like and what you'd like them to do differently. If they also 68 | 69 | respond in a non-constructive way to this private discussion, or it doesn't have 70 | 71 | the intended effect, then 72 | 73 | escalate to your manager as 74 | 75 | appropriate. 76 | ja: >- 77 | 一般に、レビュアーが建設的で礼儀正しい言い方でフィードバックをしてくれない場合、そのことを対面で伝えましょう。対面やビデオ通話で会話する機会が持てなければ、個人的なメールを送りましょう。レビュアーの言い方のどこが嫌でどんなふうに変えてほしいのかを丁重に説明してください。この個人的な会話でもレビュアーが非建設的な言い方で応酬するようなら、あるいは態度が全く変わらないようなら、上司に相談するのが適切です。 78 | --- 79 | texts: 80 | en: Fix the Code {#code} 81 | ja: コードを修正する {#code} 82 | --- 83 | texts: 84 | en: >- 85 | If a reviewer says that they don't understand something in your code, your first 86 | 87 | response should be to clarify the code itself. If the code can't be clarified, 88 | 89 | add a code comment that explains why the code is there. If a comment seems 90 | 91 | pointless, only then should your response be an explanation in the code review 92 | 93 | tool. 94 | ja: >- 95 | レビュアーがあなたのコードに理解できない箇所があると言うなら、最初に行うべきはコード自体を明確にすることです。コードを明確にできないなら、なぜそのコードがそこにあるのか理由を書いたコメントをコードに追加してください。コメントの追加では足りない場合に限り、コードレビューツール上で説明してください。 96 | --- 97 | texts: 98 | en: >- 99 | If a reviewer didn't understand some piece of your code, it's likely other 100 | 101 | future readers of the code won't understand either. Writing a response in the 102 | 103 | code review tool doesn't help future code readers, but clarifying your code or 104 | 105 | adding code comments does help them. 106 | ja: >- 107 | レビュアーがあなたのコードを理解できければ、将来コードを読む人も理解できない可能性が高いです。コードレビューツール上で説明しても将来コードを読む人には役立ちませんが、コード自体を整理したりコードにコメントを追加したりすれば、将来コードを読むにも役立ちます。 108 | --- 109 | texts: 110 | en: Think for Yourself {#think} 111 | ja: 自分で考える {#think} 112 | --- 113 | texts: 114 | en: >- 115 | Writing a CL can take a lot of work. It's often really satisfying to finally 116 | 117 | send one out for review, feel like it's done, and be pretty sure that no further 118 | 119 | work is needed. So when a reviewer comes back with comments on things that could 120 | 121 | be improved, it's easy to reflexively think the comments are wrong, the reviewer 122 | 123 | is blocking you unnecessarily, or they should just let you submit the CL. 124 | 125 | However, **no matter how certain you are** at this point, take a moment to step 126 | 127 | back and consider if the reviewer is providing valuable feedback that will help 128 | 129 | the codebase and Google. Your first question to yourself should always be, "Is 130 | 131 | the reviewer correct?" 132 | ja: >- 133 | CL を書くのは大きな労力が伴います。CL をレビューに送り出すとすっかり満足して、これで仕事が完了したと感じ、これ以上作業が必要ないと思い込んでしまうことがよくあります。そうなるとレビュアーが改善点についてコメントを返しても、コメントのほうが間違っていて、レビュアーがあなたを不必要にブロックしているとか、つべこべ言わずに CL を取り込んでくれればいいのにとか反射的に考えてしまいやすいものです。けれども、そのときに**どれだけ自分が正しいと確信していたとしても**、少し立ち止まって、レビュアーがコードベースと Google を良くする価値あるフィードバックを書いているのではないかと考えてみてください。常日頃から「レビュアーが正しいのではないか？」と自問自答してください。 134 | --- 135 | texts: 136 | en: >- 137 | If you can't answer that question, it's likely the reviewer needs to clarify 138 | 139 | their comments. 140 | ja: その問いに答えを出せないとしたら、レビュアーのコメントがわかりにくいのが原因と考えられるので、レビュアーがもっと明解に書く必要があります。 141 | --- 142 | texts: 143 | en: >- 144 | If you *have* considered it and you still think you're right, feel free to 145 | 146 | respond with an explanation of why your method of doing things is better for the 147 | 148 | codebase, users, and/or Google. Often, reviewers are actually providing 149 | 150 | *suggestions* and they want you to think for yourself about what's best. You 151 | 152 | might actually know something about the users, codebase, or CL that the reviewer 153 | 154 | doesn't know. So fill them in; give them more context. Usually you can come to 155 | 156 | some consensus between yourself and the reviewer based on technical facts. 157 | ja: >- 158 | その問いを**考えた**上でなお自分が正しいと思えるなら、あなたのやり方のほうがコードベースにとってもユーザーにとっても、また Google にとっても良いといえる理由を気兼ねなく説明してください。レビュアーは実際には**提案**をしていて、何が最良なのかは開発者自身に考えてほしいと思っていることがよくあります。開発者はユーザーについて、コードベースについて、CL についてレビュアーの知らないことを知っていることもあります。そういうときには知識のギャップを埋めてください。レビュアーにコンテキストをもっと与えてください。技術的な事実に基づいて開発者とレビュアーの間で一定のコンセンサスに達することができるでしょう。 159 | --- 160 | texts: 161 | en: Resolving Conflicts {#conflicts} 162 | ja: 意見の対立を解消する {#conflicts} 163 | --- 164 | texts: 165 | en: >- 166 | Your first step in resolving conflicts should always be to try to come to 167 | 168 | consensus with your reviewer. If you can't achieve consensus, see 169 | 170 | [The Standard of Code Review](../reviewer/standard.md), which gives principles 171 | 172 | to follow in such a situation. 173 | ja: >- 174 | 意見の対立を解消するためにまず行うべきはレビュアーとコンセンサスを得られるよう試みることです。コンセンサスに達することができない場合、[コードレビューの基準](../reviewer/standard.md)にそういった状況で対応する際の原則があるので参考にしてください。 175 | -------------------------------------------------------------------------------- /locales/review/developer/index.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: The CL author's guide to getting through code review 3 | ja: コードレビューを通過するための CL 作成者のガイド 4 | --- 5 | texts: 6 | en: >- 7 | The pages in this section contain best practices for developers going through 8 | 9 | code review. These guidelines should help you get through reviews faster and 10 | 11 | with higher-quality results. You don't have to read them all, but they are 12 | 13 | intended to apply to every Google developer, and many people have found it 14 | 15 | helpful to read the whole set. 16 | ja: このセクションでは、開発者がコードレビューにパスするためのベストプラクティスを説明します。ここにあるガイドラインは開発者がコードレビューを素早く通過し、品質の高い結果を残すのに役立つでしょう。すべてを読む必要はありませんが、このガイドラインは Google の全開発者に適用できるように作られているため、全体を通して読むのが有益であるという感想を持つ人が多いです。 17 | --- 18 | texts: 19 | en: "[Writing Good CL Descriptions](cl-descriptions.md)" 20 | ja: "[適切な CL のディスクリプションを書く](cl-descriptions.md)" 21 | --- 22 | texts: 23 | en: "[Small CLs](small-cls.md)" 24 | ja: "[小さな CL](small-cls.md)" 25 | --- 26 | texts: 27 | en: "[How to Handle Reviewer Comments](handling-comments.md)" 28 | ja: "[レビューコメントの対応の仕方](handling-comments.md)" 29 | --- 30 | texts: 31 | en: >- 32 | See also [How to Do a Code Review](../reviewer/), which gives detailed guidance 33 | 34 | for code reviewers. 35 | ja: "[コードレビューの仕方](../reviewer/)も参考にしてください。こちらはコードレビュアーのための詳細なガイドです。" 36 | -------------------------------------------------------------------------------- /locales/review/developer/small-cls.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: Small CLs 3 | ja: 小さな CL 4 | --- 5 | texts: 6 | en: Why Write Small CLs? {#why} 7 | ja: どうして小さな CL を書くのか？ {#why} 8 | --- 9 | texts: 10 | en: "Small, simple CLs are:" 11 | ja: 小さくシンプルな CL には以下のような利点があります。 12 | --- 13 | texts: 14 | en: >- 15 | **Reviewed more quickly.** It's easier for a reviewer to find five minutes 16 | several times to review small CLs than to set aside a 30 minute block to 17 | review one large CL. 18 | ja: >- 19 | **速くレビューできる。**レビュアーにとって、小さな CL をレビューするための 5 分間を数回確保するほうが、一度の大きな CL をレビューするための 30 分をまとめて確保するよりも容易です。 20 | --- 21 | texts: 22 | en: >- 23 | **Reviewed more thoroughly.** With large changes, reviewers and authors tend 24 | to get frustrated by large volumes of detailed commentary shifting back and 25 | forth—sometimes to the point where important points get missed or dropped. 26 | ja: >- 27 | **隅々までレビューできる。**変更が大規模だとあっちこっちに詳細なコメントを大量に書かねばならず、レビュアーと作成者がストレスを感じやすくなります。ときには重要な点を見落としたり省略したりしてしまうこともあります。 28 | --- 29 | texts: 30 | en: >- 31 | **Less likely to introduce bugs.** Since you're making fewer changes, it's 32 | easier for you and your reviewer to reason effectively about the impact of 33 | the CL and see if a bug has been introduced. 34 | ja: >- 35 | **バグが混入する可能性が減る。**変更箇所が少なければ、開発者もレビュアーも CL の影響範囲が予測しやすく、バグが混入したかどうかを見分けやすくなります。 36 | --- 37 | texts: 38 | en: >- 39 | **Less wasted work if they are rejected.** If you write a huge CL and then 40 | your reviewer says that the overall direction is wrong, you've wasted a lot 41 | of work. 42 | ja: > 43 | **CL が却下されても無駄になる作業が少ない。**巨大な CL を書いてからレビュアーに全体的な方向性が間違っていると言われると、多くの作業が無駄になってしまいます。 44 | --- 45 | texts: 46 | en: >- 47 | **Easier to merge.** Working on a large CL takes a long time, so you will 48 | have lots of conflicts when you merge, and you will have to merge 49 | frequently. 50 | ja: >- 51 | **マージしやすい。**大規模な CL での作業には時間がかかるため、マージする頃には多くのコンフリクトが発生し、頻繁にマージしなければならなくなります。 52 | --- 53 | texts: 54 | en: >- 55 | **Easier to design well.** It's a lot easier to polish the design and code 56 | health of a small change than it is to refine all the details of a large 57 | change. 58 | ja: >- 59 | **設計を改善しやすくなる。**小さな変更の設計やコードの健康状態を改善するほうが、大きな変更の詳細をすべて見直して設計を洗練させるよりもずっと簡単です。 60 | --- 61 | texts: 62 | en: >- 63 | **Less blocking on reviews.** Sending self-contained portions of your 64 | overall change allows you to continue coding while you wait for your current 65 | CL in review. 66 | ja: >- 67 | **レビューによって作業がブロックされなくなる。**あなたがしようとしている変更全体のうち一部を自己完結的な CL にして提出すれば、現在の CL のレビューを待つ間にコーディング作業を続けることができます。 68 | --- 69 | texts: 70 | en: >- 71 | **Simpler to roll back.** A large CL will more likely touch files that get 72 | updated between the initial CL submission and a rollback CL, complicating 73 | the rollback (the intermediate CLs will probably need to be rolled back 74 | too). 75 | ja: >- 76 | **ロールバックしやすい。**大きな CL は多くのファイルにわたって変更するため、最初に CL を提出してからロールバックの CL までにそれらのファイルが変更され、ロールバックが複雑になります。（その CL 以降の CL もロールバックする必要が生じることもあります） 77 | --- 78 | texts: 79 | en: >- 80 | Note that **reviewers have discretion to reject your change outright for the 81 | 82 | sole reason of it being too large.** Usually they will thank you for your 83 | 84 | contribution but request that you somehow make it into a series of smaller 85 | 86 | changes. It can be a lot of work to split up a change after you've already 87 | 88 | written it, or require lots of time arguing about why the reviewer should accept 89 | 90 | your large change. It's easier to just write small CLs in the first place. 91 | ja: >- 92 | 注意していただきたいのですが、**レビュアーにはあなたの変更が大きすぎるというそれだけの理由でただちにその変更を却下できる裁量があります。**普通はそこまでせず、レビュアーはあなたの貢献に感謝しつつも、もっと小さな変更に分けて CL を送ってほしいとリクエストするでしょう。すでにコードを書いたあとで変更を分割するのは骨の折れる作業になりますし、あるいは巨大な変更を受け入れてもらうにしてもレビュアーが納得できるよう議論を交わすのにも多くの時間が必要になります。最初から小さな CL を書くほうが簡単です。 93 | --- 94 | texts: 95 | en: What is Small? {#what_is_small} 96 | ja: 「小さい」とはどういうことか？ {#what_is_small} 97 | --- 98 | texts: 99 | en: >- 100 | In general, the right size for a CL is **one self-contained change**. This means 101 | 102 | that: 103 | ja: 一般に、CL の適切なサイズは**単一の自己完結的な変更**です。これは以下のことを意味します。 104 | --- 105 | texts: 106 | en: >- 107 | The CL makes a minimal change that addresses **just one thing**. This is 108 | usually just one part of a feature, rather than a whole feature at once. In 109 | general it's better to err on the side of writing CLs that are too small vs. 110 | CLs that are too large. Work with your reviewer to find out what an 111 | acceptable size is. 112 | ja: >- 113 | CL が**ただ一つのこと**に取り組むミニマルな変更を行っています。これは普通、ある機能の全体を一度に実装するというより、その中の一部分だけを実装する CL です。小さすぎる CL を書いて失敗するほうが大きすぎる CL を書いて失敗するよりもよほど良いです。レビュアーと協力してどんなサイズの CL なら受け入れられるかを探ってみてください。 114 | --- 115 | texts: 116 | en: >- 117 | Everything the reviewer needs to understand about the CL (except future 118 | development) is in the CL, the CL's description, the existing codebase, or a 119 | CL they've already reviewed. 120 | ja: >- 121 | レビュアーがその CL について理解する必要のあるすべての情報 (将来の開発を除く) が CLや、CL ディスクリプション、既存のコードベース、これまでレビューした CL の中にあります。 122 | --- 123 | texts: 124 | en: >- 125 | The system will continue to work well for its users and for the developers 126 | after the CL is checked in. 127 | ja: システムはその CL がチェックインされたあともユーザーにとっても開発者にとっても正常に動作し続けます。 128 | --- 129 | texts: 130 | en: >- 131 | The CL is not so small that its implications are difficult to understand. If 132 | you add a new API, you should include a usage of the API in the same CL so 133 | that reviewers can better understand how the API will be used. This also 134 | prevents checking in unused APIs. 135 | ja: CL がその含意がわかりにくくなるほどに過剰に小さくはありません。新しい API を追加するのなら、同じ CL の中にその API の使い方を含めるべきです。それはレビュアーが API の使い方をきちんと理解できるようになるためです。こうすることは、使われていない API のチェックインを防止します。 136 | --- 137 | texts: 138 | en: >- 139 | There are no hard and fast rules about how large is "too large." 100 lines is 140 | 141 | usually a reasonable size for a CL, and 1000 lines is usually too large, but 142 | 143 | it's up to the judgment of your reviewer. The number of files that a change is 144 | 145 | spread across also affects its "size." A 200-line change in one file might be 146 | 147 | okay, but spread across 50 files it would usually be too large. 148 | ja: >- 149 | どれほど大きければ「大きすぎる」と言えるのかを判断する厳密で手っ取り早いルールはありません。大雑把には 100 行の CL は適度なサイズで、1000 行になると大きすぎると言えますが、これもレビュアーの判断次第です。変更するファイル数も CL の「サイズ」に関係あります。200 行の変更が行われていてもそれが 1 つのファイルで完結していれば許容できるかもしれませんが、 50 ファイルにもわたる変更であれば普通は「大きすぎる」と判断されるでしょう。 150 | --- 151 | texts: 152 | en: >- 153 | Keep in mind that although you have been intimately involved with your code from 154 | 155 | the moment you started to write it, the reviewer often has no context. What 156 | 157 | seems like an acceptably-sized CL to you might be overwhelming to your reviewer. 158 | 159 | When in doubt, write CLs that are smaller than you think you need to write. 160 | 161 | Reviewers rarely complain about getting CLs that are too small. 162 | ja: >- 163 | 覚えておいていただきたいのですが、あなたはコードを書き始めた瞬間からコードに没頭していて目を閉じてもコードを思い浮かべられるとしても、レビュアーは何のコンテキストも持たないことがよくあります。あなたにとって許容範囲な CL のサイズのように思えても、レビュアーにとっては大きすぎるかもしれません。CL が小さすぎるからといってそのことで不満をこぼすレビュアーはめったにいません。 164 | --- 165 | texts: 166 | en: When are Large CLs Okay? {#large_okay} 167 | ja: どのようなときに大きな CL でも良いか？ {#large_okay} 168 | --- 169 | texts: 170 | en: "There are a few situations in which large changes aren't as bad:" 171 | ja: 大きな変更でも許される状況が例外的にあります。 172 | --- 173 | texts: 174 | en: >- 175 | You can usually count deletion of an entire file as being just one line of 176 | change, because it doesn't take the reviewer very long to review. 177 | ja: >- 178 | 一つのファイルをまるごと削除する場合は、一行だけの変更とみなしても構いません。レビューするのにそれほど長い時間がかからないからです。 179 | --- 180 | texts: 181 | en: >- 182 | Sometimes a large CL has been generated by an automatic refactoring tool 183 | that you trust completely, and the reviewer's job is just to sanity check 184 | and say that they really do want the change. These CLs can be larger, 185 | although some of the caveats from above (such as merging and testing) still 186 | apply. 187 | ja: >- 188 | 大規模な CL がリファクタリングツールによって自動生成される場合があります。そのツールをあなたが完全に信頼していれば、そういった CL が大きくても構いません。レビュアーの仕事は正常に動作していることを確認して、意図通りに変更されていると言うだけです。このような CL は大きくなっても構いません。ただし、上で述べた注意書き（マージやテストなど）はこの場合にも適用されます。 189 | --- 190 | texts: 191 | en: Splitting by Files {#splitting-files} 192 | ja: ファイルによる分割 {#splitting-files} 193 | --- 194 | texts: 195 | en: >- 196 | Another way to split up a CL is by groupings of files that will require 197 | 198 | different reviewers but are otherwise self-contained changes. 199 | ja: CL を分割する他のやり方として、別々のレビュアーを必要とするという点を除けば自己完結的な変更となる複数のファイルをひとまとめにグループ分けするというのがあります。 200 | --- 201 | texts: 202 | en: >- 203 | For example: you send off one CL for modifications to a protocol buffer and 204 | 205 | another CL for changes to the code that uses that proto. You have to submit the 206 | 207 | proto CL before the code CL, but they can both be reviewed simultaneously. If 208 | 209 | you do this, you might want to inform both sets of reviewers about the other CL 210 | 211 | that you wrote, so that they have context for your changes. 212 | ja: >- 213 | 例1: ある protocol buffer を修正する CL を一つ送り、その proto を使用するコードを変更する CL を別で送ります。proto 変更の CL をコード変更の CL よりも先に提出する必要がありますが、二つの CL は同時にレビューを受けられます。この場合、両レビュアーに変更のコンテキストを提供するため他方の CL に関する情報を知らせてもよいでしょう。 214 | --- 215 | texts: 216 | en: >- 217 | Another example: you send one CL for a code change and another for the 218 | 219 | configuration or experiment that uses that code; this is easier to roll back 220 | 221 | too, if necessary, as configuration/experiment files are sometimes pushed to 222 | 223 | production faster than code changes. 224 | ja: >- 225 | 例2: コード変更の CL を一つ送り、そのコードを使用する構成や実験のために CL を別で送ります。このやり方では必要ならロールバックも容易にできます。構成・実験用のファイルはコード変更よりも素早くプロダクションにプッシュされることがあるからです。 226 | --- 227 | texts: 228 | en: Separate Out Refactorings {#refactoring} 229 | ja: リファクタリングを分離する {#refactoring} 230 | --- 231 | texts: 232 | en: >- 233 | It's usually best to do refactorings in a separate CL from feature changes or 234 | 235 | bug fixes. For example, moving and renaming a class should be in a different CL 236 | 237 | from fixing a bug in that class. It is much easier for reviewers to understand 238 | 239 | the changes introduced by each CL when they are separate. 240 | ja: 機能変更やバグ修正と、リファクタリングは別の CL にするのが普通はベストです。たとえば、クラスを移動したりクラス名を変更したりはそのクラスのバグ修正とは別の CL にするべきです。別々の CL に分けておけば、レビュアーは変更を理解しやすくなります。 241 | --- 242 | texts: 243 | en: >- 244 | Small cleanups such as fixing a local variable name can be included inside of a 245 | 246 | feature change or bug fix CL, though. It's up to the judgment of developers and 247 | 248 | reviewers to decide when a refactoring is so large that it will make the review 249 | 250 | more difficult if included in your current CL. 251 | ja: >- 252 | とはいえ、ローカル変数の名前を変えるといった小さな修正は機能変更やバグ修正の CL に含めても構いません。どんなときにリファクタリングが大きすぎるかは開発者とレビュアーの判断により決まります。リファクタリングを現在の CL に含めるとレビューがしにくくなるようなら、CL を分割してください。 253 | --- 254 | texts: 255 | en: Keep related test code in the same CL {#test_code} 256 | ja: 関連するテストコードを同じ CL に含める {#test_code} 257 | --- 258 | texts: 259 | en: >- 260 | Avoid splitting test code into a separate CL. Tests validating your code 261 | 262 | modifications should go into the same CL, even if it increases the code line 263 | 264 | count. 265 | ja: >- 266 | テストコードを別の CL に分けるのは避けてください。コードの修正を検証するテストはコード変更の行数が増えるとしても同じ CL に入れてください。 267 | --- 268 | texts: 269 | en: >- 270 | However, independent test modifications can go into separate CLs first, 271 | 272 | similar to the [refactorings guidelines](#refactoring). That includes: 273 | ja: >- 274 | けれども、**独立した**テストの修正は別々の CL にして先に提出しても構いません。[リファクタリングのガイドライン](#refactoring)と同様です。たとえば以下のような場合です。 275 | --- 276 | texts: 277 | en: validating pre-existing, submitted code with new tests. 278 | ja: 提出済みの既存コードを新たなテストで検証する 279 | --- 280 | texts: 281 | en: refactoring the test code (e.g. introduce helper functions). 282 | ja: "テストコードのリファクタリング (例: helper 関数の導入)" 283 | --- 284 | texts: 285 | en: introducing larger test framework code (e.g. an integration test). 286 | ja: "より大きなテストフレームワークのコードの導入 (例: 統合テスト)" 287 | --- 288 | texts: 289 | en: Don't Break the Build {#break} 290 | ja: ビルドを壊さない {#break} 291 | --- 292 | texts: 293 | en: >- 294 | If you have several CLs that depend on each other, you need to find a way to 295 | 296 | make sure the whole system keeps working after each CL is submitted. Otherwise 297 | 298 | you might break the build for all your fellow developers for a few minutes 299 | 300 | between your CL submissions (or even longer if something goes wrong unexpectedly 301 | 302 | with your later CL submissions). 303 | ja: >- 304 | 相互に依存する複数の CL がある場合、CL の提出後もシステム全体が動作するようにする方法を見つける必要があります。そうしないと、すべての CL 提出が完了するまでの間にビルドを壊してしまい、同僚の開発者に迷惑をかけるかもしれません。(あるいは後の CL 提出に何か予期せぬ間違いがあると、ビルドの壊れた状態がもっと長引くこともあります。) 305 | --- 306 | texts: 307 | en: Can't Make it Small Enough {#cant} 308 | ja: 十分小さくできない場合 {#cant} 309 | --- 310 | texts: 311 | en: >- 312 | Sometimes you will encounter situations where it seems like your CL *has* to be 313 | 314 | large. This is very rarely true. Authors who practice writing small CLs can 315 | 316 | almost always find a way to decompose functionality into a series of small 317 | 318 | changes. 319 | ja: "CL を大きく**せざるをえない**ように思える状況になることがあります。非常に稀ですが、そういう状況は確かにあります。小さな CL を書く習慣が定着している開発者は、ほとんどどんな場合でも一機能を複数の小さな変更に分解する方法を見出すことができます。" 320 | --- 321 | texts: 322 | en: >- 323 | Before writing a large CL, consider whether preceding it with a refactoring-only 324 | 325 | CL could pave the way for a cleaner implementation. Talk to your teammates and 326 | 327 | see if anybody has thoughts on how to implement the functionality in small CLs 328 | 329 | instead. 330 | ja: >- 331 | 大規模な CL を書く前に、事前にリファクタリングだけの CL を送ればもっとすっきりした実装をする方法が用意できるのではないかと考えてみてください。また、チームメンバーに相談し、その機能を小さな CL に分割できる実装方法を考えつくかどうか確認してみてください。 332 | --- 333 | texts: 334 | en: >- 335 | If all of these options fail (which should be extremely rare) then get consent 336 | 337 | from your reviewers in advance to review a large CL, so they are warned about 338 | 339 | what is coming. In this situation, expect to be going through the review process 340 | 341 | for a long time, be vigilant about not introducing bugs, and be extra diligent 342 | 343 | about writing tests. 344 | ja: >- 345 | 上記の施策でもうまく行かない場合 (非常に稀ですが)、大きな CL をレビューすることについて事前にレビュアーから同意を得てください。そうすればレビュアーはこれから来る CL の心構えができます。この状況では、レビュープロセスに時間がかかることが予想されます。バグを生み出さないよう細心の注意を払い、普段以上にテストをしっかり書いてください。 346 | --- 347 | texts: 348 | en: "Next: [How to Handle Reviewer Comments](handling-comments.md)" 349 | ja: "次: [レビューコメントの対応の仕方](handling-comments.md)" 350 | -------------------------------------------------------------------------------- /locales/review/emergencies.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: Emergencies 3 | ja: 緊急事態 4 | --- 5 | texts: 6 | en: >- 7 | Sometimes there are emergency CLs that must pass through the entire code review 8 | 9 | process as quickly as 10 | 11 | possible. 12 | ja: 緊急の CL というものがときどきあります。緊急の CL は可能な限りすみやかにコードレビューの全プロセスを通過させる必要があります。 13 | --- 14 | texts: 15 | en: What Is An Emergency? {#what} 16 | ja: 緊急事態とは何か？ {#what} 17 | --- 18 | texts: 19 | en: >- 20 | An emergency CL would be a **small** change that: allows a major launch to 21 | 22 | continue instead of rolling back, fixes a bug significantly affecting users in 23 | 24 | production, handles a pressing legal issue, closes a major security hole, etc. 25 | ja: >- 26 | 緊急の CL は**小さな**変更になるでしょう。たとえば、ローンチ済みの主要機能をロールバックするのではなく継続するための変更、本番環境のユーザーに重大な影響を与えるバグの修正、切迫した法的問題の対応、深刻なセキュリティホールの修正等です。 27 | --- 28 | texts: 29 | en: >- 30 | In emergencies we really do care about the speed of the entire code review 31 | 32 | process, not just the [speed of response](reviewer/speed.md). In this case 33 | 34 | *only*, the reviewer should care more about the speed of the review and the 35 | 36 | correctness of the code (does it actually resolve the emergency?) than anything 37 | 38 | else. Also (perhaps obviously) such reviews should take priority over all other 39 | 40 | code reviews, when they come up. 41 | ja: >- 42 | 緊急事態で私達が尽力するのはレビューの[応答の速さ](reviewer/speed.md)だけでなくコードレビューのプロセス全体の速度です。この場合に**限り**、レビュアーはすみやかにレビューすることとコードの正確さ (緊急事態を本当に解決しているだろうか？) に何よりも集中してください。また、(当然かもしれませんが) このレビュー依頼が来たら他のレビューよりも最優先で取り組んでください。 43 | --- 44 | texts: 45 | en: >- 46 | However, after the emergency is resolved you should look over the emergency CLs 47 | 48 | again and give them a [more thorough review](reviewer/looking-for.md). 49 | ja: >- 50 | しかしながら、緊急事態が解決したあとは緊急の CL をもう一度見て、[全体的なレビュー](reviewer/looking-for.md)を再度行ってください。 51 | --- 52 | texts: 53 | en: What Is Not An Emergency? {#not} 54 | ja: 緊急事態でないものは何か？ {#not} 55 | --- 56 | texts: 57 | en: "To be clear, the following cases are *not* an emergency:" 58 | ja: はっきりさせるために、緊急事態**でない**ものを以下に挙げます。 59 | --- 60 | texts: 61 | en: >- 62 | Wanting to launch this week rather than next week (unless there is some 63 | actual [hard deadline](#deadlines) for launch such as a partner agreement). 64 | ja: >- 65 | ローンチを来週から今週に早めたい (例外としてパートナーの同意のような[ハードな納期](#deadlines)が実際にある場合は別です) 66 | --- 67 | texts: 68 | en: >- 69 | The developer has worked on a feature for a very long time and they really 70 | want to get the CL in. 71 | ja: >- 72 | 開発者がある機能について非常に長期間にわたって作業しているため、CL をそろそろいい加減取り込んでほしい。 73 | --- 74 | texts: 75 | en: >- 76 | The reviewers are all in another timezone where it is currently nighttime or 77 | they are away on an off-site. 78 | ja: >- 79 | レビュアーが皆、他のタイムゾーンにいて今は夜だったり現場にいなかったりする。 80 | --- 81 | texts: 82 | en: >- 83 | It is the end of the day on a Friday and it would just be great to get this 84 | CL in before the developer leaves for the weekend. 85 | ja: >- 86 | 今が金曜日の終業間際で、開発者が週末に去る前にこの CL を取り込んでもらえると素敵だ 87 | --- 88 | texts: 89 | en: >- 90 | A manager says that this review has to be complete and the CL checked in 91 | today because of a [soft (not hard) deadline](#deadlines). 92 | ja: >- 93 | マネージャーが [(ハードでなく) ソフトな納期](#deadlines)のためにこのレビューを今日中に完了させて CL を取り入れなければならないと言っている 94 | --- 95 | texts: 96 | en: Rolling back a CL that is causing test failures or build breakages. 97 | ja: テストの失敗やビルドの破壊を引き起こしている CL のロールバック 98 | --- 99 | texts: 100 | en: And so on. 101 | ja: "" 102 | --- 103 | texts: 104 | en: What Is a Hard Deadline? {#deadlines} 105 | ja: ハードな納期とは何か？ {#deadlines} 106 | --- 107 | texts: 108 | en: >- 109 | A hard deadline is one where **something disastrous would happen** if you miss 110 | 111 | it. For example: 112 | ja: ハードな納期とはそれを逃すと**大きな損害が発生する**納期のことです。たとえば以下のようなものです。 113 | --- 114 | texts: 115 | en: >- 116 | Submitting your CL by a certain date is necessary for a contractual 117 | obligation. 118 | ja: 契約上の義務からある期日までに CL を提出する必要がある。 119 | --- 120 | texts: 121 | en: >- 122 | Your product will completely fail in the marketplace if not released by a 123 | certain date. 124 | ja: ある期日までにリリースしなければそのプロダクトが市場で完全に乗り遅れてしまう。 125 | --- 126 | texts: 127 | en: >- 128 | Some hardware manufacturers only ship new hardware once a year. If you miss 129 | the deadline to submit code to them, that could be disastrous, depending on 130 | what type of code you’re trying to ship. 131 | ja: あるハードウェアメーカーは新しいハードウェアを年に一度しかリリースしない。納期までにコードを提出しないと、リリースしようとしているコードの種類によっては大きな損害が発生する。 132 | --- 133 | texts: 134 | en: >- 135 | Delaying a release for a week is not disastrous. Missing an important conference 136 | 137 | might be disastrous, but often is not. 138 | ja: "リリースが一週間遅れても大きな損害にはなりません。重要なカンファレンスを逃すと損害が大きくなるかもしれませんが、とはいえ頻繁に起こるケースではありません。" 139 | --- 140 | texts: 141 | en: >- 142 | Most deadlines are soft deadlines, not hard deadlines. They represent a desire 143 | 144 | for a feature to be done by a certain time. They are important, but you 145 | 146 | shouldn’t be sacrificing code health to make them. 147 | ja: ほとんどの納期はソフトな納期であって、ハードな納期ではありません。ある機能が期日までに実装されてほしいという願望を述べているだけです。それは重要ではありますが、そのためにコードの健康状態を犠牲にすべきではありません。 148 | --- 149 | texts: 150 | en: >- 151 | If you have a long release cycle (several weeks) it can be tempting to sacrifice 152 | 153 | code review quality to get a feature in before the next cycle. However, this 154 | 155 | pattern, if repeated, is a common way for projects to build up overwhelming 156 | 157 | technical debt. If developers are routinely submitting CLs near the end of the 158 | 159 | cycle that "must get in" with only superficial review, then the team should 160 | 161 | modify its process so that large feature changes happen early in the cycle and 162 | 163 | have enough time for good review. 164 | ja: リリースサイクルが数週間にわたる長い期間だったりすると、次のサイクルに入る前にコードレビューの品質を犠牲にしてまである機能を取り入れてしまいたいという誘惑があることがあります。けれども、このパターンが繰り返されると、プロジェクト技術的負債があるとき噴出することになります。開発者が CL をリリースサイクルの終盤に提出し、表面をなぞるだけのレビューで CL を「取り入れなければならない」といったことが習慣的に行われているなら、チームは開発プロセスを見直すべきです。大きな機能変更はリリースサイクルの初期に提出し、きちんとレビューするための時間を十分に確保できるようにしてください。 165 | -------------------------------------------------------------------------------- /locales/review/index.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: Code Review Developer Guide 3 | ja: コードレビュー開発者ガイド 4 | --- 5 | texts: 6 | en: Introduction {#intro} 7 | ja: はじめに {#intro} 8 | --- 9 | texts: 10 | en: >- 11 | A code review is a process where someone other than the author(s) of a piece of 12 | 13 | code examines that code. 14 | ja: >- 15 | コードレビューとは、コードの作成者以外の人がコードを調べるプロセスです。 16 | --- 17 | texts: 18 | en: At Google we use code review to maintain the quality of our code and products. 19 | ja: Google ではコードとプロダクトの品質を維持するためにコードレビューを実施しています。 20 | --- 21 | texts: 22 | en: >- 23 | This documentation is the canonical description of Google's code review 24 | 25 | processes and policies. 26 | ja: このドキュメントは Google のコードレビューのプロセスとポリシーに関する正規の解説です。 27 | --- 28 | texts: 29 | en: >- 30 | This page is an overview of our code review process. There are two other large 31 | 32 | documents that are a part of this guide: 33 | ja: >- 34 | このページでは私達のコードレビュープロセスを概観します。このガイドはさらに二つのドキュメントに分けられます。 35 | --- 36 | texts: 37 | en: >- 38 | **[How To Do A Code Review](reviewer/)**: A detailed guide for code 39 | reviewers. 40 | ja: >- 41 | **[コードレビューの仕方](reviewer/)**: コードレビュアーのための詳細なガイド 42 | --- 43 | texts: 44 | en: >- 45 | **[The CL Author's Guide](developer/)**: A detailed guide for developers 46 | whose CLs are going through review. 47 | ja: >- 48 | **[CL 作成者のガイド](developer/)**: CL をレビューしてもらう開発者のための詳細なガイド 49 | --- 50 | texts: 51 | en: What Do Code Reviewers Look For? {#look_for} 52 | ja: コードレビュアーはどんな観点でレビューすべきか？ {#look_for} 53 | --- 54 | texts: 55 | en: "Code reviews should look at:" 56 | ja: "コードレビューは次の観点で見るべきです。" 57 | --- 58 | texts: 59 | en: "**Design**: Is the code well-designed and appropriate for your system?" 60 | ja: "**設計**: コードはうまく設計され、そのシステムにとって適切か？" 61 | --- 62 | texts: 63 | en: >- 64 | **Functionality**: Does the code behave as the author likely intended? Is 65 | the way the code behaves good for its users? 66 | ja: >- 67 | **機能性**: コードは作成者の意図通りに動作するか？ユーザーにとってコードの挙動は適切か？ 68 | --- 69 | texts: 70 | en: >- 71 | **Complexity**: Could the code be made simpler? Would another developer be 72 | able to easily understand and use this code when they come across it in the 73 | future? 74 | ja: >- 75 | **複雑さ**: コードはもっとシンプルにできるか？コードを作成した開発者があとになってもう一度そのコードに触れたとき、理解しやすく使いやすいか？ 76 | --- 77 | texts: 78 | en: "**Tests**: Does the code have correct and well-designed automated tests?" 79 | ja: "**テスト**: そのコードには、正確で、うまく設計され、自動化されたテストがあるか？" 80 | --- 81 | texts: 82 | en: >- 83 | **Naming**: Did the developer choose clear names for variables, classes, 84 | methods, etc.? 85 | ja: >- 86 | **命名**: 変数名、クラス名、メソッド名などに明解な名前を選んだか？ 87 | --- 88 | texts: 89 | en: "**Comments**: Are the comments clear and useful?" 90 | ja: "**コメント**: コメントは明解で有益か？" 91 | --- 92 | texts: 93 | en: >- 94 | **Style**: Does the code follow our 95 | [style guides](http://google.github.io/styleguide/)? 96 | ja: >- 97 | **スタイル**: コードは[スタイルガイド](http://google.github.io/styleguide/)に準拠しているか？ 98 | --- 99 | texts: 100 | en: "**Documentation**: Did the developer also update relevant documentation?" 101 | ja: "**ドキュメント**: 関連するドキュメントも更新してあるか？" 102 | --- 103 | texts: 104 | en: See **[How To Do A Code Review](reviewer/)** for more information. 105 | ja: "詳細は**[コードレビューの仕方](reviewer/)**を確認してください。" 106 | --- 107 | texts: 108 | en: Picking the Best Reviewers {#best_reviewers} 109 | ja: 最高のレビュアーを選ぶ {#best_reviewers} 110 | --- 111 | texts: 112 | en: >- 113 | In general, you want to find the *best* reviewers you can who are capable of 114 | 115 | responding to your review within a reasonable period of time. 116 | ja: >- 117 | 一般的に、レビュアーを探すとなれば合理的な時間内でレビューに反応してくれる**最高の**レビュアーを見つけたいと思うでしょう。 118 | --- 119 | texts: 120 | en: >- 121 | The best reviewer is the person who will be able to give you the most thorough 122 | 123 | and correct review for the piece of code you are writing. This usually means the 124 | 125 | owner(s) of the code, who may or may not be the people in the OWNERS file. 126 | 127 | Sometimes this means asking different people to review different parts of the 128 | 129 | CL. 130 | ja: >- 131 | 最高のレビュアーとは、あなたが書いたコードにすみずみまで正確なレビューをしてくれる人です。 132 | 133 | 多くの場合、最高のレビュアーはコードの所有者です。OWNERS ファイルに記載されていることもありますが、そうでないこともあります。 134 | 135 | ときには CL の変更箇所をいくつかに分けて、それぞれ別の人にレビューをお願いするのが相応しい場合もあります。 136 | --- 137 | texts: 138 | en: >- 139 | If you find an ideal reviewer but they are not available, you should at least CC 140 | 141 | them on your change. 142 | ja: >- 143 | 理想的なレビュアーを見つけたとしても彼らが忙しくてレビューできないこともあります。そういうときでも少なくとも彼らを変更の CC に割り当てるべきです。 144 | --- 145 | texts: 146 | en: In-Person Reviews {#in_person} 147 | ja: 対面でのレビュー {#in_person} 148 | --- 149 | texts: 150 | en: >- 151 | If you pair-programmed a piece of code with somebody who was qualified to do a 152 | 153 | good code review on it, then that code is considered reviewed. 154 | ja: >- 155 | 適切なコードレビューをする資格のある人とペアプログラミングで書いたコードは、レビュー済みとみなせます。 156 | --- 157 | texts: 158 | en: >- 159 | You can also do in-person code reviews where the reviewer asks questions and the 160 | 161 | developer of the change speaks only when spoken to. 162 | ja: >- 163 | また、対面でコードレビューを受けることもできます。レビュアーが質問をし、コードの作成者が質問に答えるという形です。 164 | --- 165 | texts: 166 | en: See Also {#seealso} 167 | ja: 参考 {#seealso} 168 | --- 169 | texts: 170 | en: "[How To Do A Code Review](reviewer/): A detailed guide for code reviewers." 171 | ja: "[コードレビューの仕方](reviewer/): コードレビュアーのための詳細なガイド" 172 | --- 173 | texts: 174 | en: >- 175 | [The CL Author's Guide](developer/): A detailed guide for developers whose 176 | CLs are going through review. 177 | ja: "[CL 作成者のガイド](developer/): CL がレビューを受けている開発者のための詳細なガイド" 178 | -------------------------------------------------------------------------------- /locales/review/reviewer/comments.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: How to write code review comments 3 | ja: レビューコメントの書き方 4 | --- 5 | texts: 6 | en: Summary 7 | ja: 要約 8 | --- 9 | texts: 10 | en: Be kind. 11 | ja: コメントは丁重に 12 | --- 13 | texts: 14 | en: Explain your reasoning. 15 | ja: 理由を説明してください 16 | --- 17 | texts: 18 | en: >- 19 | Balance giving explicit directions with just pointing out problems and 20 | letting the developer decide. 21 | ja: 問題の指摘に加えて明確な方向性を示すことと、開発者本人に決定を委ねることをバランス良く行ってください 22 | --- 23 | texts: 24 | en: >- 25 | Encourage developers to simplify code or add code comments instead of just 26 | explaining the complexity to you. 27 | ja: 複雑なコードを見つけたらそれを説明してもらうだけで終わらせず、コードをシンプルにしてもらうとかコードにコメントを追加するよう開発者に勧めてください 28 | --- 29 | texts: 30 | en: Courtesy 31 | ja: 礼儀正しさ 32 | --- 33 | texts: 34 | en: >- 35 | In general, it is important to be 36 | 37 | courteous and respectful while also being 38 | 39 | very clear and helpful to the developer whose code you are reviewing. One way to 40 | 41 | do this is to be sure that you are always making comments about the *code* and 42 | 43 | never making comments about the *developer*. You don't always have to follow 44 | 45 | this practice, but you should definitely use it when saying something that might 46 | 47 | otherwise be upsetting or contentious. For example: 48 | ja: >- 49 | 一般論として、あなたがレビューしているコードの開発者にコメントを送るとき、明確で有益な内容であることもちろん大切ですが、礼儀正しく敬意を払った書き方であることも大切です。 50 | 51 | それを実践する一つの方法は、必ず**コード**についてコメントし、**開発者本人**についてコメントしないよう心がけることです。 52 | 53 | この慣例に杓子定規に従う必要はありませんが、相手を傷つけたり怒らせたりするかもしれない繊細な内容を書くときには必ずそうするようにしてください。 54 | 55 | 以下はその例です。 56 | --- 57 | texts: 58 | en: >- 59 | Bad: "Why did **you** use threads here when there's obviously no benefit to be 60 | 61 | gained from concurrency?" 62 | ja: 悪い例「並行処理にしても明らかにメリットがないのに、どうして**あなたは**スレッドを使ったのですか？」 63 | --- 64 | texts: 65 | en: >- 66 | Good: "The concurrency model here is adding complexity to the system without any 67 | 68 | actual performance benefit that I can see. Because there's no performance 69 | 70 | benefit, it's best for this code to be single-threaded instead of using multiple 71 | 72 | threads." 73 | ja: 良い例「見たところ、ここで使った並行処理モデルは実際にはパフォーマンス上のメリットがないまま、ただシステムを複雑にしています。パフォーマンス上のメリットがないので、複数スレッドを使わずにシングルスレッドのコードにするのが最善です」 74 | --- 75 | texts: 76 | en: Explain Why {#why} 77 | ja: 「なぜ」を説明する {#why} 78 | --- 79 | texts: 80 | en: >- 81 | One thing you'll notice about the "good" example from above is that it helps the 82 | 83 | developer understand *why* you are making your comment. You don't always need to 84 | 85 | include this information in your review comments, but sometimes it's appropriate 86 | 87 | to give a bit more explanation around your intent, the best practice you're 88 | 89 | following, or how your suggestion improves code health. 90 | ja: >- 91 | 上の「良い例」でひとつお気づきでしょうが、あなたが書いているコメントの「理由」を開発者が理解することは有益です。 92 | 93 | レビューコメントに必ずこの情報を含める必要があるかというと、そうではありませんが、それが適切な場合があります。 94 | 95 | そういうときには、コメントの意図についてもう少し詳しく説明したり、あなたが参考にしているベストプラクティスを教えたり、あなたの提案がどのようにコードの健康状態を良くするのかを解説したりしてください。 96 | --- 97 | texts: 98 | en: Giving Guidance {#guidance} 99 | ja: 指示を与える {#guidance} 100 | --- 101 | texts: 102 | en: >- 103 | **In general it is the developer's responsibility to fix a CL, not the 104 | 105 | reviewer's.** You are not required to do detailed design of a solution or write 106 | 107 | code for the developer. 108 | ja: >- 109 | **CL を修正するのは一般的に開発者の責任であって、レビュアーの責任ではありません。**ソリューションの詳細な設計をしたり開発者の代わりのコードを書いたりする仕事はレビュアーに求められていません。 110 | --- 111 | texts: 112 | en: >- 113 | This doesn't mean the reviewer should be unhelpful, though. In general you 114 | 115 | should strike an appropriate balance between pointing out problems and providing 116 | 117 | direct guidance. Pointing out problems and letting the developer make a decision 118 | 119 | often helps the developer learn, and makes it easier to do code reviews. It also 120 | 121 | can result in a better solution, because the developer is closer to the code 122 | 123 | than the reviewer is. 124 | ja: >- 125 | とはいえ、レビュアーは手助けしないでただ突き放せばよいということではありません。 126 | 127 | 一般にレビュアーは、問題を指摘することと指示を直接与えることを適度にバランス良く行うべきです。 128 | 129 | 問題を指摘して決定を開発者本人に任せることは、しばしば開発者が自分で学ぶ機会になりますし、コードレビューが楽になります。 130 | 131 | また、開発者はレビュアーよりもコードを間近で見ているので、開発者に任せるほうが良いソリューションになることもあります。 132 | --- 133 | texts: 134 | en: >- 135 | However, sometimes direct instructions, suggestions, or even code are more 136 | 137 | helpful. The primary goal of code review is to get the best CL possible. A 138 | 139 | secondary goal is improving the skills of developers so that they require less 140 | 141 | and less review over time. 142 | ja: >- 143 | その一方で、直接的な指示や提案や、ときにはコードを見せることがさらに有益になる場合もあります。 144 | 145 | コードレビューの主要な目的は CL の品質をできる限り良くすることです。 146 | 147 | 第二の目的は、開発者のスキルを向上させ、長期的にレビューを不要にすることです。 148 | --- 149 | texts: 150 | en: Accepting Explanations {#explanations} 151 | ja: 説明を受け入れる {#explanations} 152 | --- 153 | texts: 154 | en: >- 155 | If you ask a developer to explain a piece of code that you don't understand, 156 | 157 | that should usually result in them **rewriting the code more clearly**. 158 | 159 | Occasionally, adding a comment in the code is also an appropriate response, as 160 | 161 | long as it's not just explaining overly complex code. 162 | ja: >- 163 | あなたが理解できないコードを開発者に説明してもらうのは、多くの場合、**コードをもっと明確に書き直してもらう**ほうが良い結果になります。 164 | 165 | ときには、複雑すぎるコードを説明してもらうだけでなく、コードにコメントを追加するのも適切な応答になります。 166 | --- 167 | texts: 168 | en: >- 169 | **Explanations written only in the code review tool are not helpful to future 170 | 171 | code readers.** They are acceptable only in a few circumstances, such as when 172 | 173 | you are reviewing an area you are not very familiar with and the developer 174 | 175 | explains something that normal readers of the code would have already known. 176 | ja: "**コードレビューツールの中に説明を書き残しても、将来そのコードを読む人にとって役に立ちません。**ツールにコメントを残すのが受け入れられるケースは、限られた状況だけです。たとえば、あなたがあまり詳しくない分野のレビューをしていて、通常そのコードを読む開発者はすでによく知っているような情報を説明してもらうときには、ツールにコメントを残せば十分です。" 177 | --- 178 | texts: 179 | en: "Next: [Handling Pushback in Code Reviews](pushback.md)" 180 | ja: "次: [コードレビュー中の取り下げに対応する](pushback.md)" 181 | -------------------------------------------------------------------------------- /locales/review/reviewer/index.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: How to do a code review 3 | ja: コードレビューの仕方 4 | --- 5 | texts: 6 | en: >- 7 | The pages in this section contain recommendations on the best way to do code 8 | 9 | reviews, based on long experience. All together they represent one complete 10 | 11 | document, broken up into many separate sections. You don't have to read them 12 | 13 | all, but many people have found it very helpful to themselves and their team to 14 | 15 | read the entire set. 16 | ja: >- 17 | このセクションでは、長年の経験に基づいて、コードレビューをする最良の方法に関するいろいろな推奨事項を説明しています。 18 | 19 | 各ページをひとまとめにすると一つの完全なドキュメントになりますが、便宜上、多くのセクションに分割しています。 20 | 21 | 全部を読む必要はありませんが、多数の感想によれば、ドキュメントを通読するのが個人としてもチームとしても非常に有益です。 22 | --- 23 | texts: 24 | en: "[The Standard of Code Review](standard.md)" 25 | ja: "[コードレビューの基準](standard.md)" 26 | --- 27 | texts: 28 | en: "[What to Look For In a Code Review](looking-for.md)" 29 | ja: "[コードレビューの観点](looking-for.md)" 30 | --- 31 | texts: 32 | en: "[Navigating a CL in Review](navigate.md)" 33 | ja: "[レビューで CL を閲覧する](navigate.md)" 34 | --- 35 | texts: 36 | en: "[Speed of Code Reviews](speed.md)" 37 | ja: "[コードレビューのスピード](speed.md)" 38 | --- 39 | texts: 40 | en: "[How to Write Code Review Comments](comments.md)" 41 | ja: "[コードレビューコメントの書き方](comments.md)" 42 | --- 43 | texts: 44 | en: "[Handling Pushback in Code Reviews](pushback.md)" 45 | ja: "[コードレビュー中の取り下げに対応する](pushback.md)" 46 | --- 47 | texts: 48 | en: >- 49 | See also the [CL Author's Guide](../developer/), which gives detailed guidance 50 | 51 | to developers whose CLs are undergoing review. 52 | ja: >- 53 | [CL 作成者のガイド](../developer/)も参考にしてください。こちらは CL をコードレビューしてもらう側の開発者のための詳細なガイドです。 54 | -------------------------------------------------------------------------------- /locales/review/reviewer/looking-for.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: What to look for in a code review 3 | ja: コードレビューの観点 4 | --- 5 | texts: 6 | en: >- 7 | Note: Always make sure to take into account 8 | 9 | [The Standard of Code Review](standard.md) when considering each of these 10 | 11 | points. 12 | ja: （注）以下のポイントを検討する際にはつねに[コードレビューの基準](standard.md)を忘れないでください。 13 | --- 14 | texts: 15 | en: Design 16 | ja: 設計 17 | --- 18 | texts: 19 | en: >- 20 | The most important thing to cover in a review is the overall design of the CL. 21 | 22 | Do the interactions of various pieces of code in the CL make sense? Does this 23 | 24 | change belong in your codebase, or in a library? Does it integrate well with the 25 | 26 | rest of your system? Is now a good time to add this functionality? 27 | ja: >- 28 | レビューで確認すべき最も大切なことは、CL の全体的な設計です。 29 | 30 | CL のコードの各部分は相互にきちんと連携するでしょうか？この変更はコードベースに属するものでしょうか、それともあるライブラリに属するものでしょうか？システムの他の部分とうまく統合するでしょうか？この機能を追加するタイミングは今がふさわしいでしょうか？ 31 | --- 32 | texts: 33 | en: Functionality 34 | ja: 機能性 35 | --- 36 | texts: 37 | en: >- 38 | Does this CL do what the developer intended? Is what the developer intended good 39 | 40 | for the users of this code? The "users" are usually both end-users (when they 41 | 42 | are affected by the change) and developers (who will have to "use" this code in 43 | 44 | the future). 45 | ja: この CL は開発者の意図通りに動作しますか？開発者の意図はこのコードのユーザーにとって適切でしょうか？「ユーザー」とは普通、エンドユーザー（その変更によって影響を受ける場合）と開発者（将来このコードを「使う」必要のある人）の両方を指します。 46 | --- 47 | texts: 48 | en: >- 49 | Mostly, we expect developers to test CLs well-enough that they work correctly by 50 | 51 | the time they get to code review. However, as the reviewer you should still be 52 | 53 | thinking about edge cases, looking for concurrency problems, trying to think 54 | 55 | like a user, and making sure that there are no bugs that you see just by reading 56 | 57 | the code. 58 | ja: >- 59 | 通常、CL がコードレビューに至るまでには、コードが正しく動作することを開発者が十分にテストしていると期待できます。 60 | 61 | それでもレビュアーはエッジケースを想定する、並行処理の問題を探す、ユーザーになりきって考えるなど、コードを読むだけではわからない不具合がないかを確認してください。 62 | --- 63 | texts: 64 | en: >- 65 | You *can* validate the CL if you want—the time when it's most important for a 66 | 67 | reviewer to check a CL's behavior is when it has a user-facing impact, such as a 68 | 69 | **UI change**. It's hard to understand how some changes will impact a user when 70 | 71 | you're just reading the code. For changes like that, you can have the developer 72 | 73 | give you a demo of the functionality if it's too inconvenient to patch in the CL 74 | 75 | and try it yourself. 76 | ja: >- 77 | 必要に応じて CL を検証しても**構いません**。特に、**UI の変更**といった、ユーザーに影響する変更があるときには、レビュアーが CL の動作を確認するべき最も重要な機会です。 78 | 79 | 変更がユーザーにどのような影響を与えるかはコードを読むだけではわかりにくいものです。 80 | 81 | そのような変更に対して、CL の変更を反映して自分で動作確認するのが難しければ、開発者にその機能のデモを依頼することもできます。 82 | --- 83 | texts: 84 | en: >- 85 | Another time when it's particularly important to think about functionality 86 | 87 | during a code review is if there is some sort of **parallel programming** going 88 | 89 | on in the CL that could theoretically cause deadlocks or race conditions. These 90 | 91 | sorts of issues are very hard to detect by just running the code and usually 92 | 93 | need somebody (both the developer and the reviewer) to think through them 94 | 95 | carefully to be sure that problems aren't being introduced. (Note that this is 96 | 97 | also a good reason not to use concurrency models where race conditions or 98 | 99 | deadlocks are possible—it can make it very complex to do code reviews or 100 | 101 | understand the code.) 102 | ja: >- 103 | また別のケースですが、コードレビュー中に機能について熟慮が特に求められるのは、CL にある種の**並行プログラミング**が行われていて、理論的にデッドロックや競合状態を引き起こす可能性がある場合です。 104 | 105 | こういう問題はコードを実行するだけでは不具合の発見が難しいため、通常、コード全体を見て問題が発生していないことを注意深く確認する人（開発者とレビュアーの両方）が必要です。 106 | 107 | （なお、これこそがやはり、競合状態やデッドロックが発生しうるところで並行処理モデルを採用すべきでない十分な理由です。コードレビューを行うにしてもコードを理解するにしても非常に複雑になりうるからです。） 108 | --- 109 | texts: 110 | en: Complexity 111 | ja: 複雑性 112 | --- 113 | texts: 114 | en: >- 115 | Is the CL more complex than it should be? Check this at every level of the 116 | 117 | CL—are individual lines too complex? Are functions too complex? Are classes too 118 | 119 | complex? "Too complex" usually means **"can't be understood quickly by code 120 | 121 | readers."** It can also mean **"developers are likely to introduce bugs when 122 | 123 | they try to call or modify this code."** 124 | ja: >- 125 | CL が必要以上に複雑になっていないでしょうか？ CL のあらゆるレベルで確認してください。 126 | 127 | 一行一行は複雑すぎないでしょうか？関数は複雑すぎないでしょうか？クラスは複雑すぎないでしょうか？ 128 | 129 | 「複雑すぎる」とは普通、**「コードを読んですぐに理解できない」**という意味です。 130 | 131 | あるいは、**「開発者がこのコードを呼び出したり修正したりしようとするときに不具合を生み出す可能性がある」**という意味でもあります。 132 | --- 133 | texts: 134 | en: >- 135 | A particular type of complexity is **over-engineering**, where developers have 136 | 137 | made the code more generic than it needs to be, or added functionality that 138 | 139 | isn't presently needed by the system. Reviewers should be especially vigilant 140 | 141 | about over-engineering. Encourage developers to solve the problem they know 142 | 143 | needs to be solved *now*, not the problem that the developer speculates *might* 144 | 145 | need to be solved in the future. The future problem should be solved once it 146 | 147 | arrives and you can see its actual shape and requirements in the physical 148 | 149 | universe. 150 | ja: >- 151 | あるタイプの複雑性は、**オーバーエンジニアリング**です。開発者が必要以上にコードを一般化していたり、現在のシステムにとってまだ必要のない機能を盛り込んでいたりするということです。 152 | 153 | レビュアーはオーバーエンジニアリングを特に警戒すべきです。 154 | 155 | 開発者には、**現在**解決する必要のある既知の問題に取り組むべきであって、将来解決する必要が出てくる**かもしれない**推測に基づいた問題には目を向けないよう勧めてください。 156 | 157 | 将来の問題はそれが発生してから取り組めばよいのです。問題が発生すれば、この物理的な宇宙の中でその実際の形と要件を知ることができます。 158 | --- 159 | texts: 160 | en: Tests 161 | ja: テスト 162 | --- 163 | texts: 164 | en: >- 165 | Ask for unit, integration, or end-to-end 166 | 167 | tests as appropriate for the change. In general, tests should be added in the 168 | 169 | same CL as the production code unless the CL is handling an 170 | 171 | [emergency](../emergencies.md). 172 | ja: >- 173 | 変更に適したユニットテスト、結合テスト、E2E テストを依頼してください。 174 | 175 | 一般に、テストはプロダクションコードと同じ CL に追加してください。 176 | 177 | 例外は、CL が[緊急事態](../emergencies.md)に対処している場合です。 178 | --- 179 | texts: 180 | en: >- 181 | Make sure that the tests in the CL are correct, sensible, and useful. Tests do 182 | 183 | not test themselves, and we rarely write tests for our tests—a human must ensure 184 | 185 | that tests are valid. 186 | ja: >- 187 | CL の中のテストが正確で、適切で、有用であることを確認してください。 188 | 189 | テストがテストコード自体をテストすることはありませんし、テストのためのテストコードを書くこともめったにありません。テストの有効性は人間が確認しなければなりません。 190 | --- 191 | texts: 192 | en: >- 193 | Will the tests actually fail when the code is broken? If the code changes 194 | 195 | beneath them, will they start producing false positives? Does each test make 196 | 197 | simple and useful assertions? Are the tests separated appropriately between 198 | 199 | different test methods? 200 | ja: >- 201 | コードが壊れているときにテストはきちんと失敗するでしょうか？ 202 | 203 | そのテストの下でコードを変更すると、テストが誤検知を起こさないでしょうか？ 204 | 205 | 各テストはシンプルで有用なアサーションを使っているでしょうか？ 206 | 207 | テストは異なるテストメソッドごとに適切に分割されているでしょうか？ 208 | --- 209 | texts: 210 | en: >- 211 | Remember that tests are also code that has to be maintained. Don't accept 212 | 213 | complexity in tests just because they aren't part of the main binary. 214 | ja: >- 215 | テストもまた保守すべきコードであることを覚えていてください。 216 | 217 | メインのバイナリに含まれないからといって、テストが複雑になるのを許容しないでください。 218 | --- 219 | texts: 220 | en: Naming 221 | ja: 命名 222 | --- 223 | texts: 224 | en: >- 225 | Did the developer pick good names for everything? A good name is long enough to 226 | 227 | fully communicate what the item is or does, without being so long that it 228 | 229 | becomes hard to read. 230 | ja: >- 231 | 開発者はあらゆるものに適切な名前を与えているでしょうか？ 232 | 233 | 適切な名前とは、それが何であるか／何をするかを伝えるのに十分に長く、しかし読むのに困難を覚えないほど短いものです。 234 | --- 235 | texts: 236 | en: Comments 237 | ja: コメント 238 | --- 239 | texts: 240 | en: >- 241 | Did the developer write clear comments in understandable English? Are all of the 242 | 243 | comments actually necessary? Usually comments are useful when they **explain 244 | 245 | why** some code exists, and should not be explaining *what* some code is doing. 246 | 247 | If the code isn't clear enough to explain itself, then the code should be made 248 | 249 | simpler. There are some exceptions (regular expressions and complex algorithms 250 | 251 | often benefit greatly from comments that explain what they're doing, for 252 | 253 | example) but mostly comments are for information that the code itself can't 254 | 255 | possibly contain, like the reasoning behind a decision. 256 | ja: >- 257 | 開発者はわかりやすい英語で明確なコメントを書きましたか？ 258 | 259 | すべてのコメントは実際に必要でしょうか？ 260 | 261 | コメントは普通、あるコードが**「なぜ」**存在するのかを説明するのに役立ちますが、コードが**「何」**をしているのかを説明すべきではありません。 262 | 263 | コードがそれ自身を説明するほど明確でないのなら、コードをもっとシンプルにすべきです。 264 | 265 | 例外はあります（たとえば正規表現や複雑なアルゴリズムでは何をしているのかを説明するコメントは非常に有益です）が、ほとんどの場合、コメントは決定の背後にある理由といった、コード自体が語ることのできない情報を伝えるために書きます。 266 | --- 267 | texts: 268 | en: >- 269 | It can also be helpful to look at comments that were there before this CL. Maybe 270 | 271 | there is a TODO that can be removed now, a comment advising against this change 272 | 273 | being made, etc. 274 | ja: >- 275 | CL の前にその箇所にあったコメントに注目するのが有益であることもあります。 276 | 277 | 今となっては削除すべき TODO があるかもしれませんし、この変更を行うべきではないと助言するコメントなどがあるかもしれません。 278 | --- 279 | texts: 280 | en: >- 281 | Note that comments are different from *documentation* of classes, modules, or 282 | 283 | functions, which should instead express the purpose of a piece of code, how it 284 | 285 | should be used, and how it behaves when used. 286 | ja: なお、コメントはクラス、モジュール、関数の**ドキュメンテーション**とは違います。ドキュメンテーションコメントはコードの目的や、使い方や、使われたときのふるまいを記述するものです。 287 | --- 288 | texts: 289 | en: Style 290 | ja: スタイル 291 | --- 292 | texts: 293 | en: >- 294 | We have [style guides](http://google.github.io/styleguide/) at Google for all 295 | 296 | of our major languages, and even for most of the minor languages. Make sure the 297 | 298 | CL follows the appropriate style guides. 299 | ja: >- 300 | Google には[スタイルガイド](http://google.github.io/styleguide/)があります。メジャーな言語に関してはすべて、マイナーな言語でも多くはスタイルガイドが揃っています。 301 | 302 | CL が適切なスタイルガイドを従っているかを確認してください。 303 | --- 304 | texts: 305 | en: >- 306 | If you want to improve some style point that isn't in the style guide, prefix 307 | 308 | your comment with "Nit:" to let the developer know that it's a nitpick that you 309 | 310 | think would improve the code but isn't mandatory. Don't block CLs from being 311 | 312 | submitted based only on personal style preferences. 313 | ja: >- 314 | スタイルガイドに記載のないスタイルの改善をしたい場合、コメントに「Nit:」というプレフィックスを付けて、それが細かい指摘 (nitpick) であることを開発者に知らせるのがよいでしょう。そうすると、コードを修正してほしいが強制ではないということが伝わります。 315 | 316 | 個人的なスタイルの好みで CL の提出をブロックしないでください。 317 | --- 318 | texts: 319 | en: >- 320 | The author of the CL should not include major style changes combined with other 321 | 322 | changes. It makes it hard to see what is being changed in the CL, makes merges 323 | 324 | and rollbacks more complex, and causes other problems. For example, if the 325 | 326 | author wants to reformat the whole file, have them send you just the 327 | 328 | reformatting as one CL, and then send another CL with their functional changes 329 | 330 | after that. 331 | ja: >- 332 | CL の作成者はスタイル上の大きな変更を他の変更に混ぜないようにしてください。 333 | 334 | それをすると CL で何が変更されているのかを見るのが難しくなるばかりか、マージ後にロールバックするのはもっと大変ですし、さらに他の問題も引き起こします。 335 | 336 | たとえば、作成者がファイル全体を再フォーマットしたいと思ったら、再フォーマットだけを一つの CL として提出し、その後で機能的な変更を別の CL として提出するようにしてください。 337 | --- 338 | texts: 339 | en: Documentation 340 | ja: ドキュメンテーション 341 | --- 342 | texts: 343 | en: >- 344 | If a CL changes how users build, test, interact with, or release code, check to 345 | 346 | see that it also updates associated documentation, including 347 | 348 | READMEs, g3doc pages, and any generated 349 | 350 | reference docs. If the CL deletes or deprecates code, consider whether the 351 | 352 | documentation should also be deleted. 353 | 354 | If documentation is 355 | 356 | missing, ask for it. 357 | ja: >- 358 | CL がコードのビルド、テスト、相互連携、リリースのやり方を変更する場合、それに関連するドキュメンテーションも更新しているかを確認してください。 359 | 360 | 関連するドキュメンテーションには、README、g3doc ページ、自動生成されたリファレンスドキュメントなどがあります。 361 | 362 | CL がコードを削除あるいは非推奨にしたら、ドキュメンテーションも削除するべきかどうか検討してください。 363 | 364 | ドキュメンテーションが存在しなければ、作成するように依頼してください。 365 | --- 366 | texts: 367 | en: Every Line {#every_line} 368 | ja: 一行ずつ {#every_line} 369 | --- 370 | texts: 371 | en: >- 372 | Look at *every* line of code that you have been assigned to review. Some things 373 | 374 | like data files, generated code, or large data structures you can scan over 375 | 376 | sometimes, but don't scan over a human-written class, function, or block of code 377 | 378 | and assume that what's inside of it is okay. Obviously some code deserves more 379 | 380 | careful scrutiny than other code 381 | ja: >- 382 | レビューをアサインされたらコードを**一行ずつ**見てください。 383 | 384 | データファイル、自動生成されたコード、巨大なデータ構造などはざっと見れば済むこともありますが、人間の書いたクラス、関数、コードブロックなどはそうもいきません。 385 | 386 | コードの中に書かれているものが正しいと決めてかからず、じっくり読んでください。 387 | 388 | 明らかに他のコードよりも精密に調べるに値するコードもあります 389 | --- 390 | texts: 391 | en: — 392 | ja: __COPY__ 393 | --- 394 | texts: 395 | en: >- 396 | that's a judgment call that you have to 397 | 398 | make 399 | ja: そうすべきかどうかはレビュアーが自分で判断しなければなりません 400 | --- 401 | texts: 402 | en: — 403 | ja: __COPY__ 404 | --- 405 | texts: 406 | en: >- 407 | but you should at least be sure that you *understand* what all the 408 | 409 | code is doing. 410 | ja: が、少なくとも全コードが何をしているかを確実に**理解**するようにしてください。 411 | --- 412 | texts: 413 | en: >- 414 | If it's too hard for you to read the code and this is slowing down the review, 415 | 416 | then you should let the developer know that 417 | 418 | and wait for them to clarify it before you try to review it. At Google, we hire 419 | 420 | great software engineers, and you are one of them. If you can't understand the 421 | 422 | code, it's very likely that other developers won't either. So you're also 423 | 424 | helping future developers understand this code, when you ask the developer to 425 | 426 | clarify it. 427 | ja: >- 428 | コードが読みにくく、そのことがレビューを遅らせているなら、レビューをいったん置いて開発者に知らせ、コードを明確にしてくれるのを待ちましょう。 429 | 430 | Google には優秀なソフトウェアエンジニアが雇われていますし、あなたはその一人です。 431 | 432 | あなたがコードを理解できないのなら、他の開発者もきっと理解できません。 433 | 434 | ですから、開発者にコードを明確にするよう依頼するのは、未来の開発者のためにこのコードを理解しやすくする手助けでもあります。 435 | --- 436 | texts: 437 | en: >- 438 | If you understand the code but you don't feel qualified to do some part of the 439 | 440 | review, make sure there is a reviewer on the CL who is qualified, particularly 441 | 442 | for complex issues such as security, concurrency, accessibility, 443 | 444 | internationalization, etc. 445 | ja: >- 446 | コードを理解できてもレビューのある部分で自分にはレビューする資格がないと感じる場合、その CL について他に適切なレビュアーがいることを忘れないでください。 447 | 448 | 特に、セキュリティ、並行処理、アクセシビリティ、インターナショナライゼーションといった複雑な問題に関しては適任者がいます。 449 | --- 450 | texts: 451 | en: Context 452 | ja: コンテキスト 453 | --- 454 | texts: 455 | en: >- 456 | It is often helpful to look at the CL in a broad context. Usually the code 457 | 458 | review tool will only show you a few lines of code around the parts that are 459 | 460 | being changed. Sometimes you have to look at the whole file to be sure that the 461 | 462 | change actually makes sense. For example, you might see only four new lines 463 | 464 | being added, but when you look at the whole file, you see those four lines are 465 | 466 | in a 50-line method that now really needs to be broken up into smaller methods. 467 | ja: >- 468 | CL を広いコンテキストの中に置いて眺めると有意義なことがよくあります。 469 | 470 | 普通コードレビューツールは変更のあった箇所の周りを数行ほど表示するだけです。 471 | 472 | 変更がうまく機能することを確認するためにファイル全体を見なければならないときもあります。 473 | 474 | たとえば、追加された行が 4 行だけだったとしても、ファイル全体を眺めたらそれが 50 行に及ぶメソッドの中に書かれていることがわかり、メソッドを分割する必要があると判明することもあります。 475 | --- 476 | texts: 477 | en: >- 478 | It's also useful to think about the CL in the context of the system as a whole. 479 | 480 | Is this CL improving the code health of the system or is it making the whole 481 | 482 | system more complex, less tested, etc.? **Don't accept CLs that degrade the code 483 | 484 | health of the system.** Most systems become complex through many small changes 485 | 486 | that add up, so it's important to prevent even small complexities in new 487 | 488 | changes. 489 | ja: >- 490 | CL をシステム全体のコンテキストの中に置いて考えてみることも有益です。 491 | 492 | この CL はシステムのコードの健康状態を改善しているでしょうか、それともシステム全体を複雑にし、テスト不足な状態にしているでしょうか？ 493 | 494 | **コードの健康状態を悪化させる CL を受け入れないでください。** 495 | 496 | ほとんどのシステムは小さな変更が積み重なってだんだんと複雑化します。 497 | 498 | だからこそ、新たな変更があったときに小さな複雑性でも混入させないようにするのが大切です。 499 | --- 500 | texts: 501 | en: Good Things {#good_things} 502 | ja: 良いこと {#good_things} 503 | --- 504 | texts: 505 | en: >- 506 | If you see something nice in the CL, tell the developer, especially when they 507 | 508 | addressed one of your comments in a great way. Code reviews often just focus on 509 | 510 | mistakes, but they should offer encouragement and appreciation for good 511 | 512 | practices, as well. It’s sometimes even more valuable, in terms of mentoring, to 513 | 514 | tell a developer what they did right than to tell them what they did wrong. 515 | ja: >- 516 | CL の中に素晴らしいものを見つけたら、開発者に教えてあげてください。特に、あなたのレビューコメントの一つに取り組んで素晴らしくやり遂げたらそうしてください。 517 | 518 | コードレビューは間違いにばかり目が行きがちですが、良い実践に対しての励ましや感謝の言葉も伝えるべきです。 519 | 520 | メンタリングの観点では、開発者が正しいこと行ったときにそれを伝えるほうが、間違いを指摘するよりもずっと価値がある場合があります。 521 | --- 522 | texts: 523 | en: Summary 524 | ja: 要約 525 | --- 526 | texts: 527 | en: "In doing a code review, you should make sure that:" 528 | ja: コードレビューをする際には、次のことを確認してください。 529 | --- 530 | texts: 531 | en: The code is well-designed. 532 | ja: コードがうまく設計されている 533 | --- 534 | texts: 535 | en: The functionality is good for the users of the code. 536 | ja: 機能性がコードのユーザーにとって適切である 537 | --- 538 | texts: 539 | en: Any UI changes are sensible and look good. 540 | ja: UI の変更がある場合、よく考えられていて見た目も適切である 541 | --- 542 | texts: 543 | en: Any parallel programming is done safely. 544 | ja: 並行処理がある場合、安全に行われている 545 | --- 546 | texts: 547 | en: The code isn't more complex than it needs to be. 548 | ja: コードが必要以上に複雑でない 549 | --- 550 | texts: 551 | en: >- 552 | The developer isn't implementing things they *might* need in the future but 553 | don't know they need now. 554 | ja: 開発者は将来必要になる**かもしれない**ものではなく、現在必要だとわかっているものを実装している 555 | --- 556 | texts: 557 | en: Code has appropriate unit tests. 558 | ja: コードには適切なユニットテストがある 559 | --- 560 | texts: 561 | en: Tests are well-designed. 562 | ja: テストがうまく設計されている 563 | --- 564 | texts: 565 | en: The developer used clear names for everything. 566 | ja: 開発者はあらゆるものに明確な名前を使った 567 | --- 568 | texts: 569 | en: Comments are clear and useful, and mostly explain *why* instead of *what*. 570 | ja: コメントは明確で有意義なもので、**「何」**ではなく**「なぜ」**を説明している 571 | --- 572 | texts: 573 | en: Code is appropriately documented (generally in g3doc). 574 | ja: コードは適切にドキュメント化されている（一般的には g3doc で） 575 | --- 576 | texts: 577 | en: The code conforms to our style guides. 578 | ja: コードはスタイルガイドに準拠している 579 | --- 580 | texts: 581 | en: >- 582 | Make sure to review **every line** of code you've been asked to review, look at 583 | 584 | the **context**, make sure you're **improving code health**, and compliment 585 | 586 | developers on **good things** that they do. 587 | ja: レビューを依頼されたコードを**一行ずつ**レビューすること、**コンテキスト**を確認すること、**コードの健康状態を改善**しているかを見極めること、開発者が**良いこと**をしたらそれを褒めることを忘れずに。 588 | --- 589 | texts: 590 | en: "Next: [Navigating a CL in Review](navigate.md)" 591 | ja: "次: [レビューで CL を閲覧する](navigate.md)" 592 | -------------------------------------------------------------------------------- /locales/review/reviewer/navigate.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: Navigating a CL in review 3 | ja: レビューで CL を閲覧する 4 | --- 5 | texts: 6 | en: Summary 7 | ja: 要約 8 | --- 9 | texts: 10 | en: >- 11 | Now that you know [what to look for](looking-for.md), what's the most efficient 12 | 13 | way to manage a review that's spread across multiple files? 14 | ja: 前節で[コードレビューの観点](looking-for.md)を学びましたが、では複数ファイルにまたがった変更をレビューする最も効果的な方法は何でしょうか？ 15 | --- 16 | texts: 17 | en: >- 18 | Does the change make sense? Does it have a good 19 | [description](../developer/cl-descriptions.md)? 20 | ja: 変更はうまく機能するでしょうか？適切な[ディスクリプション](../developer/cl-descriptions.md)はあるでしょうか？ 21 | --- 22 | texts: 23 | en: >- 24 | Look at the most important part of the change first. Is it well-designed 25 | overall? 26 | ja: いちばん重要な変更を最初に確認してください。それは全体としてうまく設計されているでしょうか？ 27 | --- 28 | texts: 29 | en: Look at the rest of the CL in an appropriate sequence. 30 | ja: CL の残りの部分を適切な順序で見てください。 31 | --- 32 | texts: 33 | en: "Step One: Take a broad view of the change {#step_one}" 34 | ja: "ステップ 1: 変更を広く眺める {#step_one}" 35 | --- 36 | texts: 37 | en: >- 38 | Look at the [CL description](../developer/cl-descriptions.md) and what the CL 39 | 40 | does in general. Does this change even make sense? If this change shouldn't have 41 | 42 | happened in the first place, please respond immediately with an explanation of 43 | 44 | why the change should not be happening. When you reject a change like this, it's 45 | 46 | also a good idea to suggest to the developer what they should have done instead. 47 | ja: >- 48 | [CL のディスクリプション](../developer/cl-descriptions.md)と CL が大まかに何をしているかを確認してください。 49 | 50 | この変更は機能しているでしょうか？ 51 | 52 | そもそもこの変更が行ってはならないものであれば、変更すべきでない理由を添えてすぐに返信してください。 53 | 54 | そのように変更を却下する場合、代わりに何をすべきかを開発者に提案するのも良い考えです。 55 | --- 56 | texts: 57 | en: >- 58 | For example, you might say "Looks like you put some good work into this, thanks! 59 | 60 | However, we're actually going in the direction of removing the FooWidget system 61 | 62 | that you're modifying here, and so we don't want to make any new modifications 63 | 64 | to it right now. How about instead you refactor our new BarWidget class?" 65 | ja: >- 66 | たとえば、次のように伝えることができます。「これに関して良い仕事をしてくださっているように思えます。ありがとう！ですが、実はあなたがここで修正した FooWidget システムは削除する方向で進めているため、今のところ新しい修正をしたくないのです。代わりに新しい BarWidget クラスをリファクタリングしていただくのはどうでしょうか？」 67 | --- 68 | texts: 69 | en: >- 70 | Note that not only did the reviewer reject the current CL and provide an 71 | 72 | alternative suggestion, but they did it *courteously*. This kind of courtesy is 73 | 74 | important because we want to show that we respect each other as developers even 75 | 76 | when we disagree. 77 | ja: >- 78 | 注意していただきたいのですが、レビュアーは現在の CL を却下して代わりの提案をしただけではなくて、それを礼儀正しく伝えました。 79 | 80 | このような礼儀正しさは重要です。私達は意見が一致しないときでも開発者として互いを尊重し合うということを示したいからです。 81 | --- 82 | texts: 83 | en: >- 84 | If you get more than a few CLs that represent changes you don't want to make, 85 | 86 | you should consider re-working your team's development process or the posted 87 | 88 | process for external contributors so that there is more communication before CLs 89 | 90 | are written. It's better to tell people "no" before they've done a ton of work 91 | 92 | that now has to be thrown away or drastically re-written. 93 | ja: >- 94 | 変更してほしくない部分を変更する CL がいくつも送られる場合、 95 | 96 | チームの開発プロセスや外部のコントリビューター向けに投稿されたプロセスを再検討してください。 97 | 98 | CL が書かれる前にもっとコミュニケーションが必要です。 99 | 100 | 人々が 1 トンもの仕事をしてその後で破棄や大部分の書き直しを迫られるよりは、事前に「ノー」と言えるほうが良いでしょう。 101 | --- 102 | texts: 103 | en: "Step Two: Examine the main parts of the CL {#step_two}" 104 | ja: "ステップ 2: CL の主要部分を調べる {#step_two}" 105 | --- 106 | texts: 107 | en: >- 108 | Find the file or files that are the "main" part of this CL. Often, there is one 109 | 110 | file that has the largest number of logical changes, and it's the major piece of 111 | 112 | the CL. Look at these major parts first. This helps give context to all of the 113 | 114 | smaller parts of the CL, and generally accelerates doing the code review. If the 115 | 116 | CL is too large for you to figure out which parts are the major parts, ask the 117 | 118 | developer what you should look at first, or ask them to 119 | 120 | [split up the CL into multiple CLs](../developer/small-cls.md). 121 | ja: >- 122 | この CL の「メイン」の部分になっているファイル（1 ファイルとは限りません）を見つけてください。 123 | 124 | よくあるのは、ロジック上の変更が最も多いファイルが一つあり、それが CL の主要部分となる場合です。 125 | 126 | これが CL の別の小さな部分にコンテキストを提供していて、それによってコードレビューが概してスムーズになります。 127 | 128 | CL があまりに巨大でどの部分が主要部分なのか判別できなければ、開発者にどこを最初に見るべきか質問してもよいですし、あるいは [CL を複数の CL に分割する](../developer/small-cls.md)ように依頼してください。 129 | --- 130 | texts: 131 | en: >- 132 | If you see some major design problems with this part of the CL, you should send 133 | 134 | those comments immediately, even if you don't have time to review the rest of 135 | 136 | the CL right now. In fact, reviewing the rest of the CL might be a waste of 137 | 138 | time, because if the design problems are significant enough, a lot of the other 139 | 140 | code under review is going to disappear and not matter anyway. 141 | ja: >- 142 | CL の主要部分に設計上の重大な問題が見つかれば、すぐにコメントを残してください。 143 | 144 | CL の残りの部分をレビューする時間があってもコメントを送るのが先です。 145 | 146 | 実際、CL の残りの部分をレビューしても時間の無駄になるかもしれません。設計上の問題が重大なものであれば、レビュー対象の他のコードは消されることになり、見ても見なくても関係なくなるからです。 147 | --- 148 | texts: 149 | en: >- 150 | There are two major reasons it's so important to send these major design 151 | 152 | comments out immediately: 153 | ja: 設計上の重大な問題に関するコメントをただちに送ることが大切な理由は二つあります。 154 | --- 155 | texts: 156 | en: >- 157 | Developers often mail a CL and then immediately start new work based on that 158 | CL while they wait for review. If there are major design problems in the CL 159 | you're reviewing, they're also going to have to re-work their later CL. You 160 | want to catch them before they've done too much extra work on top of the 161 | problematic design. 162 | ja: >- 163 | 開発者は CL を投稿すると、レビューを待ちながらその CL をベースに新しい作業をすぐに始めることがよくあります。 164 | 165 | レビュー中の CL に設計上の重大な問題があると、開発者は次の CL もやり直さなければならなくなります。 166 | 167 | 開発者が問題含みの設計の上にさらに仕事を積み上げてしまう前に引き止めたいものです。 168 | --- 169 | texts: 170 | en: >- 171 | Major design changes take longer to do than small changes. Developers nearly 172 | all have deadlines; in order to make those deadlines and still have quality 173 | code in the codebase, the developer needs to start on any major re-work of 174 | the CL as soon as possible. 175 | ja: >- 176 | 大きな設計の変更は小さな変更よりも時間がかかります。 177 | 178 | 開発者にはたいてい納期がありますが、納期を守りつつコードベースのコードの品質を保つには、CL のやり直しが重大なものであるほど、できるだけ早くやり直しに着手する必要があります。 179 | --- 180 | texts: 181 | en: "Step Three: Look through the rest of the CL in an appropriate sequence {#step_three}" 182 | ja: "ステップ 3: CL の残りを適切な順序で見る {#step_three}" 183 | --- 184 | texts: 185 | en: >- 186 | Once you've confirmed there are no major design problems with the CL as a whole, 187 | 188 | try to figure out a logical sequence to look through the files while also making 189 | 190 | sure you don't miss reviewing any file. Usually after you've looked through the 191 | 192 | major files, it's simplest to just go through each file in the order that 193 | 194 | the code review tool presents them to you. Sometimes it's also helpful to read the tests 195 | 196 | first before you read the main code, because then you have an idea of what the 197 | 198 | change is supposed to be doing. 199 | ja: >- 200 | 全体として CL に設計上の重大な問題がないことが確認できたら、次は全ファイルを一通り見て、論理的な順序を理解するようにしてください。またその際に、レビューもれのファイルがないように気をつけてください。 201 | 202 | 主要なファイルを確認し終えたら、普通はコードレビューツールが表示してくれる順序で各ファイルを調べるのがいちばん簡単です。 203 | 204 | 主要なコードを読む前にテストをまず読むのが効果的な場合もあります。 205 | 206 | そうするとこの変更が何をしようとしているのかイメージがつくからです。 207 | --- 208 | texts: 209 | en: "Next: [Speed of Code Reviews](speed.md)" 210 | ja: "次: [コードレビューのスピード](speed.md)" 211 | -------------------------------------------------------------------------------- /locales/review/reviewer/pushback.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: Handling pushback in code reviews 3 | ja: コードレビュー中の取り下げに対応する 4 | --- 5 | texts: 6 | en: >- 7 | Sometimes a developer will push back on a code review. Either they will disagree 8 | 9 | with your suggestion or they will complain that you are being too strict in 10 | 11 | general. 12 | ja: 開発者がコードレビュー中に取り下げることがあります。開発者があなたの提案に同意できないこともありますし、あなたのレビューが厳格すぎるために開発者が不満を抱いてそうすることもあります。 13 | --- 14 | texts: 15 | en: Who is right? {#who_is_right} 16 | ja: 正しいのは誰か？ {#who_is_right} 17 | --- 18 | texts: 19 | en: >- 20 | When a developer disagrees with your suggestion, first take a moment to consider 21 | 22 | if they are correct. Often, they are closer to the code than you are, and so 23 | 24 | they might really have a better insight about certain aspects of it. Does their 25 | 26 | argument make sense? Does it make sense from a code health perspective? If so, 27 | 28 | let them know that they are right and let the issue drop. 29 | ja: >- 30 | 開発者があなたの提案に同意できないとき、最初に少し考慮していただきたいのは、開発者のほうが正しいのではないかということです。 31 | 32 | よくあることですが、開発者はあなたよりもコードを間近で見ているため、ある側面では開発者のほうが優れた洞察を持っていることもあります。 33 | 34 | 開発者の議論は筋が通っているでしょうか？コードの健康状態という視点から理にかなっているでしょうか？ 35 | 36 | そうであれば、開発者が正しいということを認め、問題を水に流しましょう。 37 | --- 38 | texts: 39 | en: >- 40 | However, developers are not always right. In this case the reviewer should 41 | 42 | further explain why they believe that their suggestion is correct. A good 43 | 44 | explanation demonstrates both an understanding of the developer's reply, and 45 | 46 | additional information about why the change is being requested. 47 | ja: >- 48 | しかしながら、いつでも開発者が正しいとは限りません。その場合、レビュアーはどうして自分の提案が正しいと思うのかを踏み込んで説明しましょう。 49 | 50 | まず開発者の応答に理解を示し、それから変更が必要な理由を付け加えるのが良い説明です。 51 | --- 52 | texts: 53 | en: >- 54 | In particular, when the reviewer believes their suggestion will improve code 55 | 56 | health, they should continue to advocate for the change, if they believe the 57 | 58 | resulting code quality improvement justifies the additional work requested. 59 | 60 | **Improving code health tends to happen in small steps.** 61 | ja: >- 62 | 特に、レビュアーがコードの健康状態を良くする提案をしていると思われる場合には、その変更によってさらに作業が発生するもののそれに見合うだけコードの品質が改善すると見込まれれば、粘り強く変更を勧めるべきです。 63 | 64 | **コードの健康状態の改善は、スモールステップで行われます。** 65 | --- 66 | texts: 67 | en: >- 68 | Sometimes it takes a few rounds of explaining a suggestion before it really 69 | 70 | sinks in. Just make sure to always stay [polite](comments.md#courtesy) and let 71 | 72 | the developer know that you *hear* what they're saying, you just don't *agree*. 73 | ja: >- 74 | 提案がきちんと理解してもらえるまで何ラウンドか説明しなければならないときもありますが、いつも[丁重](comments.md#courtesy)に説明するのを忘れず、開発者の言葉にきちんと**耳を傾けた**上でただ**同意**できないだけなのだということを知らせてください。 75 | --- 76 | texts: 77 | en: Upsetting Developers {#upsetting_developers} 78 | ja: 人を悩ませる開発者 {#upsetting_developers} 79 | --- 80 | texts: 81 | en: >- 82 | Reviewers sometimes believe that the developer will be upset if the reviewer 83 | 84 | insists on an improvement. Sometimes developers do become upset, but it is 85 | 86 | usually brief and they become very thankful later that you helped them improve 87 | 88 | the quality of their code. Usually, if you are [polite](comments.md#courtesy) in 89 | 90 | your comments, developers actually don't become upset at all, and the worry is 91 | 92 | just in the reviewer's mind. Upsets are usually more about 93 | 94 | [the way comments are written](comments.md#courtesy) than about the reviewer's 95 | 96 | insistence on code quality. 97 | ja: >- 98 | レビュアーが改善を要求すると開発者が傷つくのではないかとレビュアーが思い込んでいる場合があります。確かに開発者が傷つくこともありますが、普通はそれは一時的なことで、時が経つとコードの品質改善に協力してくれたことに深く感謝するようになるものです。 99 | 100 | [丁重](comments.md#courtesy)なコメントを心がけていれば、実際、開発者は傷ついたりしません。そういった心配はレビュアーの杞憂です。 101 | 102 | 傷つくことがあるとすれば、コードの品質改善の要求よりも[コメントの書き方](comments.md#courtesy)のほうに原因があるものです。 103 | --- 104 | texts: 105 | en: Cleaning It Up Later {#later} 106 | ja: あとで片付ける {#later} 107 | --- 108 | texts: 109 | en: >- 110 | A common source of push back is that developers (understandably) want to get 111 | 112 | things done. They don't want to go through another round of review just to get 113 | 114 | this CL in. So they say they will clean something up in a later CL, and thus you 115 | 116 | should LGTM *this* CL now. Some developers are very good about this, and will 117 | 118 | immediately write a follow-up CL that fixes the issue. However, experience shows 119 | 120 | that as more time passes after a developer writes the original CL, the less 121 | 122 | likely this clean up is to happen. In fact, usually unless the developer does 123 | 124 | the clean up *immediately* after the present CL, it never happens. This isn't 125 | 126 | because developers are irresponsible, but because they have a lot of work to do 127 | 128 | and the cleanup gets lost or forgotten in the press of other work. Thus, it is 129 | 130 | usually best to insist that the developer clean up their CL *now*, before the 131 | 132 | code is in the codebase and "done." Letting people "clean things up later" is a 133 | 134 | common way for codebases to degenerate. 135 | ja: >- 136 | CL 取り下げのよくある理由は、（もっともなことですが）開発者が仕事を完了させたいからです。この CL を取り入れてもらうために何度もレビューのラウンドを重ねたくないのです。そのため、開発者はこう言います。あとで別の CL でその問題を片付けるから、**この** CL については今は LGTM してほしい、と。 137 | 138 | きちんと有言実行し、問題を解決するフォローアップの CL をすぐに書いてくれる開発者もいます。けれども、経験則が示すところによると、開発者が最初の CL を書いてから時間が経てば経つほど、その問題を片付ける可能性は低くなります。 139 | 140 | 事実、開発者が現在の CL の**直後に**問題を片付けるのでなければ、その機会は完全に消失します。こうなるのは開発者が無責任だからではなく、開発者がたくさんの仕事を抱えていて、他の仕事が押し流されて問題を片付けるのを忘れてしまったり時間を取れなくなったりするからです。 141 | 142 | ですから、最良の選択肢は普通、CL がコードベースに取り込まれて「完了 (done)」する前に、開発者に**今**片付けてもらうことです。「あとで片付ける」を許容するとコードベースは悪化します。 143 | --- 144 | texts: 145 | en: >- 146 | If a CL introduces new complexity, it must be cleaned up before submission 147 | 148 | unless it is an [emergency](../emergencies.md). If the CL exposes surrounding 149 | 150 | problems and they can't be addressed right now, the developer should file a bug 151 | 152 | for the cleanup and assign it to themselves so that it doesn't get lost. They 153 | 154 | can optionally also write a TODO comment in the code that references the filed 155 | 156 | bug. 157 | ja: CL が複雑さを新たに持ち込む場合、[緊急事態](../emergencies.md)でない限り、それが取り込まれる前にきちんと問題を片付ける必要があります。CL が周辺の問題を顕在化しているのに開発者がすぐにその問題に取り組めないときには、問題解決のためにバグを整理保存し、忘れないように自身をアサインしておきます。コードの直すべき箇所に任意で TODO コメントを入れることもできます。 158 | --- 159 | texts: 160 | en: General Complaints About Strictness {#strictness} 161 | ja: 厳格さに関するよくある不満 {#strictness} 162 | --- 163 | texts: 164 | en: >- 165 | If you previously had fairly lax code reviews and you switch to having strict 166 | 167 | reviews, some developers will complain very loudly. Improving the 168 | 169 | [speed](speed.md) of your code reviews usually causes these complaints to fade 170 | 171 | away. 172 | ja: 以前はゆるいコードレビューをしていた人が急に厳格なレビューをするようになると、開発者があからさまに不満を言うようになることがあります。コードレビューの[スピード](speed.md)を改善すると、そうした不満は解消されることが多いです。 173 | --- 174 | texts: 175 | en: >- 176 | Sometimes it can take months for these complaints to fade away, but eventually 177 | 178 | developers tend to see the value of strict code reviews as they see what great 179 | 180 | code they help generate. Sometimes the loudest protesters even become your 181 | 182 | strongest supporters once something happens that causes them to really see the 183 | 184 | value you're adding by being strict. 185 | ja: >- 186 | ときには数カ月間にわたってこうした不満がくすぶり続けることもありますが、厳格なレビュープロセスによってコードの品質が向上しているのが目に見えてわかるようになるにつれて、厳格なコードレビューの価値を見直すようになります。それどころか、厳格なレビューによって付加された価値にちょっとしたきっかけで気づくようになると、最もあからさまに反対していた開発者が、最も熱心な支持者になることさえあります。 187 | --- 188 | texts: 189 | en: Resolving Conflicts {#conflicts} 190 | ja: 意見の対立の解消 {#conflicts} 191 | --- 192 | texts: 193 | en: >- 194 | If you are following all of the above but you still encounter a conflict between 195 | 196 | yourself and a developer that can't be resolved, see 197 | 198 | [The Standard of Code Review](standard.md) for guidelines and principles that 199 | 200 | can help resolve the conflict. 201 | ja: 上記の原則に従ってレビューした結果、それでもレビュアーと開発者の間で解決できない意見の対立が生じた場合、対立を解消するためのガイドラインおよび原則として[コードレビューの基準](standard.md)を参考にしてください。 202 | -------------------------------------------------------------------------------- /locales/review/reviewer/speed.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: Speed of Code Reviews 3 | ja: コードレビューのスピード 4 | --- 5 | texts: 6 | en: Why Should Code Reviews Be Fast? {#why} 7 | ja: なぜコードレビューは素早く行うべきか？ {#why} 8 | --- 9 | texts: 10 | en: >- 11 | **At Google, we optimize for the speed at which a team of developers can produce 12 | 13 | a product together**, as opposed to optimizing for the speed at which an 14 | 15 | individual developer can write code. The speed of individual development is 16 | 17 | important, it's just not _as_ important as the velocity of the entire team. 18 | ja: >- 19 | **Google では開発者のチームが協力してプロダクトを高速に開発するために最適化しており**、開発者個人がコードを高速に書くための最適化はしません。 20 | 21 | 開発者個人のスピードは確かに重要ですが、チーム全体のスピードと比べると**同等の**重要性があるわけではありません。 22 | --- 23 | texts: 24 | en: "When code reviews are slow, several things happen:" 25 | ja: コードレビューが遅滞するとさまざまなことが起こります。 26 | --- 27 | texts: 28 | en: >- 29 | **The velocity of the team as a whole is decreased.** Yes, the individual, 30 | who doesn't respond quickly to the review, gets other work done. However, 31 | new features and bug fixes for the rest of the team are delayed by days, 32 | weeks, or months as each CL waits for review and re-review. 33 | ja: >- 34 | **チーム全体の開発速度が減少します。**もちろん、レビューに素早く反応しなくても個人としては他の仕事を終わらせられます。 35 | 36 | けれども、チームの他のメンバーが書いた新機能や不具合修正は、CL がレビュー待ち、再レビュー待ちになると何日も何週間も遅れることになります。 37 | --- 38 | texts: 39 | en: >- 40 | **Developers start to protest the code review process.** If a reviewer only 41 | responds every few days, but requests major changes to the CL each time, 42 | that can be frustrating and difficult for developers. Often, this is 43 | expressed as complaints about how "strict" the reviewer is being. If the 44 | reviewer requests the _same_ substantial changes (changes which really do 45 | improve code health) but responds _quickly_ every time the developer makes 46 | an update, the complaints tend to disappear. **Most complaints about the 47 | code review process are actually resolved by making the process faster.** 48 | ja: >- 49 | **開発者がコードレビューのプロセスに不満を持ち始めます。** 50 | 51 | レビュアーが数日おきにしか返信しないのに毎回 CL への大きな変更が要求されると、開発者はストレスをためるし開発が困難になります。 52 | 53 | よくあることですが、このようなときに表現される不満は、レビュアーが「厳しすぎる」というものです。 54 | 55 | 本質的には**同じ**変更（実際にコードの健康状態を良くする変更）でも開発者の更新に応じてレビュアーが毎回**素早く**返信すれば、このような不満は薄れます。 56 | 57 | **コードレビューに関する不満はたいていの場合、プロセスをテンポ良く進めるだけで解消します。** 58 | --- 59 | texts: 60 | en: >- 61 | **Code health can be impacted.** When reviews are slow, there is increased 62 | pressure to allow developers to submit CLs that are not as good as they 63 | could be. Slow reviews also discourage code cleanups, refactorings, and 64 | further improvements to existing CLs. 65 | ja: >- 66 | **コードの健康状態が悪い影響を受けます。** 67 | 68 | レビューが遅いと、最高の出来映えといえないような CL でもとにかく提出してしまってよいという雰囲気が開発者の間に広がります。 69 | 70 | また、レビューの遅れはコードをきれいにしたり、リファクタリングしたり、既存の CL をさらに改善したりする意欲をそぎます。 71 | --- 72 | texts: 73 | en: How Fast Should Code Reviews Be? {#fast} 74 | ja: コードレビューはどれほど急ぐべきか？ {#fast} 75 | --- 76 | texts: 77 | en: >- 78 | If you are not in the middle of a focused task, **you should do a code review 79 | 80 | shortly after it comes in.** 81 | ja: >- 82 | あるタスクに集中的に取り組んでいる最中でなければ、**コードレビューの依頼が来たらすぐに着手してください。** 83 | --- 84 | texts: 85 | en: >- 86 | **One business day is the maximum time it should take to respond** to a code 87 | 88 | review request (i.e. first thing the next morning). 89 | ja: >- 90 | コードレビューのリクエストに返信するまでの**最長の時間は一営業日**です（つまり遅くとも翌朝一番に返信すべきです）。 91 | --- 92 | texts: 93 | en: >- 94 | Following these guidelines means that a typical CL should get multiple rounds of 95 | 96 | review (if needed) within a single day. 97 | ja: >- 98 | このガイドラインに従うと、典型的な CL は（必要なら）一日以内に複数ラウンドに渡ってレビューが行われることになります。 99 | --- 100 | texts: 101 | en: Speed vs. Interruption {#interruption} 102 | ja: スピード vs 割り込み {#interruption} 103 | --- 104 | texts: 105 | en: >- 106 | There is one time where the consideration of personal velocity trumps team 107 | 108 | velocity. **If you are in the middle of a focused task, such as writing code, 109 | 110 | don't interrupt yourself to do a code review.** Research has shown that it can 111 | 112 | take a long time for a developer to get back into a smooth flow of development 113 | 114 | after being interrupted. So interrupting yourself while coding is actually 115 | 116 | _more_ expensive to the team than making another developer wait a bit for a code 117 | 118 | review. 119 | ja: >- 120 | チームの速度よりも個人の速度を尊重したほうが効率が良い場合があります。 121 | 122 | **コードを書くような集中的に取り組むべきタスク**の最中には、自分のタスクを中断してコードレビューしてはいけません。研究結果によれば、開発者が割り込み作業のあとでスムーズな開発フローに戻るには長い時間がかかることがあります。 123 | 124 | そのため、コーディングの最中に中断すると、他の開発者がコードレビューを多少待つよりも結果的に**余計な**コストがかかります。 125 | --- 126 | texts: 127 | en: >- 128 | Instead, wait for a break point in your work before you respond to a request for 129 | 130 | review. This could be when your current coding task is completed, after lunch, 131 | 132 | returning from a meeting, coming back from the microkitchen, etc. 133 | ja: >- 134 | それよりは仕事のブレークポイントを待ってからレビューのリクエストに返信しましょう。 135 | 136 | たとえば今のコーディングが完了したときや、ランチの後や、ミーティングから帰ったとき、マイクロキッチンから戻ったときなどです。 137 | --- 138 | texts: 139 | en: Fast Responses {#responses} 140 | ja: 素早い応答 {#responses} 141 | --- 142 | texts: 143 | en: >- 144 | When we talk about the speed of code reviews, it is the _response_ time that we 145 | 146 | are concerned with, as opposed to how long it takes a CL to get through the 147 | 148 | whole review and be submitted. The whole process should also be fast, ideally, 149 | 150 | but **it's even more important for the _individual responses_ to come quickly 151 | 152 | than it is for the whole process to happen rapidly.** 153 | ja: >- 154 | コードレビューのスピードについて話すとき、私達の関心は**応答**時間の長さであり、レビュー全体が完了して提出されるまでの時間の長さではありません。 155 | 156 | 理想的にはプロセス全体も短時間で行うべきですが、** _個々の応答_ を素早く行うことのほうが、プロセス全体を短時間で終えることよりも遥かに重要です。** 157 | --- 158 | texts: 159 | en: >- 160 | Even if it sometimes takes a long time to get through the entire review 161 | 162 | _process_, having quick responses from the reviewer throughout the process 163 | 164 | significantly eases the frustration developers can feel with "slow" code 165 | 166 | reviews. 167 | ja: >- 168 | たとえレビュー全体の**プロセス**に長い時間がかかってもレビュアーから素早く応答がもらえていれば、開発者が「遅い」コードレビューに感じる不満を大きく軽減できます。 169 | --- 170 | texts: 171 | en: >- 172 | If you are too busy to do a full review on a CL when it comes in, you can still 173 | 174 | send a quick response that lets the developer know when you will get to it, 175 | 176 | suggest other reviewers who might be able to respond more quickly, or 177 | 178 | [provide some initial broad comments](navigate.md). (Note: none of this means 179 | 180 | you should interrupt coding even to send a response like this 181 | ja: あなたが非常に忙しくて CL のレビュー依頼をされても十分な時間が取れない場合、それでも素早く応答することはできます。いつ着手できるかを開発者に伝えたり、もっと短時間で応答できる他のレビュアーを紹介したり、[広い観点で見た初期段階のコメントを残したり](navigate.md)できます。（注：そういった返信をするとしてもコーディングを中断するべきではありません。 182 | --- 183 | texts: 184 | en: — 185 | ja: "" 186 | --- 187 | texts: 188 | en: >- 189 | send the 190 | 191 | response at a reasonable break point in your work.) 192 | ja: 仕事中にちょうどいいブレークポイントを見つけて返信してください。） 193 | --- 194 | texts: 195 | en: >- 196 | **It is important that reviewers spend enough time on review that they are 197 | 198 | certain their "LGTM" means "this code meets [our standards](standard.md)."** 199 | 200 | However, individual responses should still ideally be [fast](#fast). 201 | ja: "**レビュアーが十分な時間を取って、「LGTM」が個人の感想でなく「このコードは[私達の基準](standard.md)を満たしている」という意味だと言えるくらいにレビューするのは大切なことです。**同時に、理想的には個々の応答は[素早く](#fast)返信すべきです。" 202 | --- 203 | texts: 204 | en: Cross-Time-Zone Reviews {#tz} 205 | ja: タイムゾーンをまたがるレビュー {#tz} 206 | --- 207 | texts: 208 | en: >- 209 | When dealing with time zone differences, try to get back to the author when they 210 | 211 | are still in the office. If they have already gone home, then try to make sure 212 | 213 | your review is done before they get back to the office the next day. 214 | ja: タイムゾーンの違いを取り回すには、CL 作成者がいつオフィスに確実にいるかを確認するようにしてください。すでに家に帰ってしまったかもしれません。そのときには翌日に作成者がオフィスに戻る前にレビューを完了するように心がけてください。 215 | --- 216 | texts: 217 | en: LGTM With Comments {#lgtm-with-comments} 218 | ja: コメント付きの LGTM {#lgtm-with-comments} 219 | --- 220 | texts: 221 | en: >- 222 | In order to speed up code reviews, there are certain situations in which a 223 | 224 | reviewer should give LGTM/Approval even though they are also leaving unresolved 225 | 226 | comments on the CL. This is done when either: 227 | ja: コードレビューのスピードを上げるために、レビュアーが CL に未解決のコメントを残しつつも LGTM / 承認を与えるというケースがあります。これは次のいずれかに当てはまる場合にそうするべきです。 228 | --- 229 | texts: 230 | en: >- 231 | The reviewer is confident that the developer will appropriately address all 232 | the reviewer's remaining comments. 233 | ja: 開発者がレビュアーの残したコメントに後で着実に取り組んでくれるとレビュアーが信頼できるとき 234 | --- 235 | texts: 236 | en: >- 237 | The remaining changes are minor and don't _have_ to be done by the 238 | developer. 239 | ja: 先送りにした変更がさほど重要でなく、開発者本人が**必ずしも**行う必要のないとき 240 | --- 241 | texts: 242 | en: >- 243 | The reviewer should specify which of these options they intend, if it is not 244 | 245 | otherwise clear. 246 | ja: これらのうちどちらがレビュアーの意図なのかをはっきりさせておかないと、曖昧な態度は開発者を混乱させます。 247 | --- 248 | texts: 249 | en: >- 250 | LGTM With Comments is especially worth considering when the developer and 251 | 252 | reviewer are in different time zones and otherwise the developer would be 253 | 254 | waiting for a whole day just to get "LGTM, Approval." 255 | ja: コメント付きの LGTM が価値を発揮するのは、特に開発者とレビュアーが別々のタイムゾーンで仕事をしているときです。このやり方でレビューを進めないと、開発者は「LGTM / 承認」をもらうためだけに丸一日待たなければならなくなります。 256 | --- 257 | texts: 258 | en: Large CLs {#large} 259 | ja: 大きな CL {#large} 260 | --- 261 | texts: 262 | en: >- 263 | If somebody sends you a code review that is so large you're not sure when you 264 | 265 | will be able to have time to review it, your typical response should be to ask 266 | 267 | the developer to 268 | 269 | [split the CL into several smaller CLs](../developer/small-cls.md) that build on 270 | 271 | each other, instead of one huge CL that has to be reviewed all at once. This is 272 | 273 | usually possible and very helpful to reviewers, even if it takes additional work 274 | 275 | from the developer. 276 | ja: >- 277 | 送られてきたコードレビューがあまりに巨大で、じっくりレビューする時間を取れるか不安なときには、開発者にその CL を[小さな CL に分割する](../developer/small-cls.md)よう依頼するのがよくある対応策です。 278 | 279 | 一度にレビューするのが大変な一つの巨大な CL ではなく、それぞれが関連している小さな CL に分割するのです。 280 | 281 | これは開発者にとってみれば仕事が増えますが、普通の CL では不可能な作業でもなく、レビュアーにとっては非常に助かります。 282 | --- 283 | texts: 284 | en: >- 285 | If a CL *can't* be broken up into smaller CLs, and you don't have time to review 286 | 287 | the entire thing quickly, then at least write some comments on the overall 288 | 289 | design of the CL and send it back to the developer for improvement. One of your 290 | 291 | goals as a reviewer should be to always unblock the developer or enable them to 292 | 293 | take some sort of further action quickly, without sacrificing code health to do 294 | 295 | so. 296 | ja: >- 297 | CL が小さな CL に分割**できない**場合、またさらにレビュアーがすぐにコード全体をレビューする時間が取れないとき、それでも少なくとも CL の全体的な設計に関してコメントを書き送り、開発者に改善を求めることができます。 298 | 299 | いつでも言えることですが、レビュアーとしてのゴールの一つは開発者を作業を滞らせないこと、あるいは次のアクションをすぐに起こせる状態にしておくことです。もちろんコードの健康状態を犠牲にしてはいけませんが。 300 | --- 301 | texts: 302 | en: Code Review Improvements Over Time {#time} 303 | ja: コードレビューを長期的に改善する {#time} 304 | --- 305 | texts: 306 | en: >- 307 | If you follow these guidelines and you are strict with your code reviews, you 308 | 309 | should find that the entire code review process tends to go faster and faster 310 | 311 | over time. Developers learn what is required for healthy code, and send you CLs 312 | 313 | that are great from the start, requiring less and less review time. Reviewers 314 | 315 | learn to respond quickly and not add unnecessary latency into the review 316 | 317 | process. 318 | 319 | But **don't compromise on 320 | 321 | the [code review standards](standard.md) or quality for an imagined improvement 322 | 323 | in velocity** 324 | ja: >- 325 | あなたがこのガイドラインに準拠してコードレビューを厳密に行っていけば、全体的なコードレビューのプロセスが時間をかけてだんだんと速くなっていくのがわかるはずです。 326 | 327 | 開発者は健康的なコードを書くために何が必要かを学び、最初から質の高い CL を送るようになり、レビューに必要な時間はだんだんと減っていきます。 328 | 329 | レビュアーは素早く応答することを学び、レビュープロセスに無駄な遅延がなくなります。 330 | 331 | それでも、**[コードレビューの基準](standard.md)に妥協しないでください。スピードを上げてもコードの品質の改善に妥協しないでください。** 332 | --- 333 | texts: 334 | en: — 335 | ja: "" 336 | --- 337 | texts: 338 | en: >- 339 | it's not actually going to make anything happen more 340 | 341 | quickly, in the long run. 342 | ja: 長期的にみれば、レビューが短時間で終えられたからといって、それだけでひとかどの仕事をしたことにはなりませんから。 343 | --- 344 | texts: 345 | en: Emergencies 346 | ja: 緊急事態 347 | --- 348 | texts: 349 | en: >- 350 | There are also [emergencies](../emergencies.md) where CLs must pass through the 351 | 352 | _whole_ review process very quickly, and where the quality guidelines would be 353 | 354 | relaxed. However, please see [What Is An Emergency?](../emergencies.md#what) for 355 | 356 | a description of which situations actually qualify as emergencies and which 357 | 358 | don't. 359 | ja: >- 360 | [緊急事態](../emergencies.md)というものもあります。緊急事態の CL は**全**レビュープロセスを素早く終えなければなりませんし、品質に関するガイドラインは緩められます。 361 | 362 | けれども、どんな状況が緊急事態に該当するのか、逆にどんな状況が緊急事態に該当しないのかを判断するために[何が緊急事態か？](../emergencies.md#what)を確認してください。 363 | --- 364 | texts: 365 | en: "Next: [How to Write Code Review Comments](comments.md)" 366 | ja: "次: [コードレビューのコメントの書き方](comments.md)" 367 | -------------------------------------------------------------------------------- /locales/review/reviewer/standard.yml: -------------------------------------------------------------------------------- 1 | texts: 2 | en: The Standard of Code Review 3 | ja: コードレビューの基準 4 | --- 5 | texts: 6 | en: >- 7 | The primary purpose of code review is to make sure that the overall 8 | 9 | code health of Google's code 10 | 11 | base is improving over time. All of the tools and processes of code review are 12 | 13 | designed to this end. 14 | ja: >- 15 | コードレビューの主な目的は、Google のコードベースにあるコードの全体的な健康状態を時間をかけて改善することです。 16 | 17 | コードレビューのすべてのツールとプロセスは、その目的のために設計されています。 18 | --- 19 | texts: 20 | en: In order to accomplish this, a series of trade-offs have to be balanced. 21 | ja: これを実現するには、さまざまなトレードオフのバランスを取る必要があります。 22 | --- 23 | texts: 24 | en: >- 25 | First, developers must be able to _make progress_ on their tasks. If you never 26 | 27 | submit an improvement to the codebase, then the codebase never improves. Also, 28 | 29 | if a reviewer makes it very difficult for _any_ change to go in, then developers 30 | 31 | are disincentivized to make improvements in the future. 32 | ja: >- 33 | まず第一に、開発者は自分のタスクを**進める**ことができなければなりません。 34 | 35 | コードベースに改善を提出できなければ、コードベースは改善しません。 36 | 37 | また、**どんな**変更に対してもレビュアーがいちいち難色を示して変更を取り入れずにいると、早晩、開発者は改善を行う意欲を失います。 38 | --- 39 | texts: 40 | en: >- 41 | On the other hand, it is the duty of the reviewer to make sure that each CL is 42 | 43 | of such a quality that the overall code health of their codebase is not 44 | 45 | decreasing as time goes on. This can be tricky, because often, codebases degrade 46 | 47 | through small decreases in code health over time, especially when a team is 48 | 49 | under significant time constraints and they feel that they have to take 50 | 51 | shortcuts in order to accomplish their goals. 52 | ja: >- 53 | 一方、CL の品質を確認するのはレビュアーの義務です。CL を取り入れてコードベースのコードの全体的な健康状態 (code health) がだんだんと悪化するのは問題ですから、きちんと確認しなければなりません。 54 | 55 | これは骨の折れるやっかいな仕事になることがあります。 56 | 57 | というのも、多くの場合、コードの健康状態を悪化させる要因が積み重なり、コードベースの品質は徐々に下がります。 58 | 59 | 特に、チームが無視できない時間的制約に縛られていて、ゴールを達成するためにはショートカットをするしかないと感じているときには、コードベースの品質は下がりやすいものです。 60 | --- 61 | texts: 62 | en: >- 63 | Also, a reviewer has ownership and responsibility over the code they are 64 | 65 | reviewing. They want to ensure that the codebase stays consistent, maintainable, 66 | 67 | and all of the other things mentioned in 68 | 69 | ["What to look for in a code review."](looking-for.md) 70 | ja: >- 71 | また、レビュアーにはレビュー中のコードに対して所有権と責任があります。 72 | 73 | レビュアーはコードベースの一貫性と保守可能性を維持し、[「コードレビューの観点」](looking-for.md)で言及されている事項を守りたいと考えています。 74 | --- 75 | texts: 76 | en: "Thus, we get the following rule as the standard we expect in code reviews:" 77 | ja: "こうして、私達はコードレビューに期待する基準として、次のルールを見出しました。" 78 | --- 79 | texts: 80 | en: >- 81 | **In general, reviewers should favor approving a CL once it is in a state where 82 | 83 | it definitely improves the overall 84 | 85 | code health of the system 86 | 87 | being worked on, even if the CL isn't perfect.** 88 | ja: >- 89 | **一般に、CL が完璧でなくても、その変更がシステムのコードの全体的な健康状態を改善すると確実にわかれば、レビュアーは CL を積極的に承認すべきである。** 90 | --- 91 | texts: 92 | en: That is _the_ senior principle among all of the code review guidelines. 93 | ja: これはコードレビューの全ガイドラインで**最上位の**原則です。 94 | --- 95 | texts: 96 | en: >- 97 | There are limitations to this, of course. For example, if a CL adds a feature 98 | 99 | that the reviewer doesn't want in their system, then the reviewer can certainly 100 | 101 | deny approval even if the code is well-designed. 102 | ja: >- 103 | もちろん、制限はあります。たとえば、CL がレビュアーが望んでいない機能をシステムに追加している場合、うまくコードが設計されてるとしてもレビュアーは承認を拒否することができます。 104 | --- 105 | texts: 106 | en: A key point here is that there is no such thing as "perfect" code 107 | ja: "ここでのポイントは、「完璧な」コードといったものは存在しないということです" 108 | --- 109 | texts: 110 | en: — 111 | ja: __COPY__ 112 | --- 113 | texts: 114 | en: >- 115 | there is 116 | 117 | only _better_ code. Reviewers should not require the author to polish every tiny 118 | 119 | piece of a CL before granting approval. Rather, the reviewer should balance out 120 | 121 | the need to make forward progress compared to the importance of the changes they 122 | 123 | are suggesting. Instead of seeking perfection, what a reviewer should seek is 124 | 125 | _continuous improvement_. A CL that, as a whole, improves the maintainability, 126 | 127 | readability, and understandability of the system shouldn't be delayed for days 128 | 129 | or weeks because it isn't "perfect." 130 | ja: >- 131 | 存在するのは**より良い**コードだけです。 132 | 133 | レビュアーは CL の承認を保留したままコードのすみずみまで磨きをかけることを要求すべきではありません。 134 | 135 | むしろ、前に進めるべきかどうかの必要性を、CL 作成者が提案している変更の重要性と比較して、バランスよく検討すべきです。 136 | 137 | レビュアーが追求すべきは、完璧さではなく**継続的な改善**です。 138 | 139 | CL が全体としてシステムの保守性、可読性、理解可能性を向上させるのなら、コードが「完璧」でないからといって数日も数週間も遅らせるべきではありません。 140 | --- 141 | texts: 142 | en: >- 143 | Reviewers should _always_ feel free to leave comments expressing that something 144 | 145 | could be better, but if it's not very important, prefix it with something like 146 | 147 | "Nit: " to let the author know that it's just a point of polish that they could 148 | 149 | choose to ignore. 150 | ja: >- 151 | レビュアーは何か改善できそうな点を見つけたら、コメントを残すのに躊躇する必要はありません。 152 | 153 | **いつでも**気軽にコメントを残すべきです。 154 | 155 | その際に、もし重要でない指摘であれば、「Nit: 」（あら探しや細かい指摘という意味）のようなプレフィックスを付けて、 156 | 157 | これはただ完全を期すための指摘なので無視してもらっても構わない、と CL 作成者に知らせると良いでしょう。 158 | --- 159 | texts: 160 | en: >- 161 | Note: Nothing in this document justifies checking in CLs that definitely 162 | 163 | _worsen_ the overall code health of the system. The only time you would do that 164 | 165 | would be in an [emergency](../emergencies.md). 166 | ja: >- 167 | （注）このドキュメントは、システムのコードの全体的な健康状態を**悪化**させるとわかりきっている CL を正当化しません。 168 | 169 | 唯一それが許されるケースは、[緊急事態](../emergencies.md)にあります。 170 | --- 171 | texts: 172 | en: Mentoring 173 | ja: メンタリング 174 | --- 175 | texts: 176 | en: >- 177 | Code review can have an important function of teaching developers something new 178 | 179 | about a language, a framework, or general software design principles. It's 180 | 181 | always fine to leave comments that help a developer learn something new. Sharing 182 | 183 | knowledge is part of improving the code health of a system over time. Just keep 184 | 185 | in mind that if your comment is purely educational, but not critical to meeting 186 | 187 | the standards described in this document, prefix it with "Nit: " or otherwise 188 | 189 | indicate that it's not mandatory for the author to resolve it in this CL. 190 | ja: >- 191 | コードレビューは、開発者に言語、フレームワーク、あるいはソフトウェア設計の一般的な原則に関して新しいことを教える重要な機会になります。 192 | 193 | 開発者が新しいことを学ぶヒントになるコメントは、いつでも歓迎されます。 194 | 195 | 知識の共有は、時間をかけてシステムのコードの健康状態を改善する試みの一部分です。 196 | 197 | 一点だけ頭に入れていただきたいのは、コメントが純粋に教育目的であって、このドキュメントで説明している基準を満たす上で重要でなければ、「Nit: 」などのプレフィックスを付けるか、この CL で作成者が解決する義務はないと付け加えてください。 198 | --- 199 | texts: 200 | en: Principles {#principles} 201 | ja: 原則 {#principles} 202 | --- 203 | texts: 204 | en: Technical facts and data overrule opinions and personal preferences. 205 | ja: 技術的な事実とデータが個人的な意見と好みをくつがえす。 206 | --- 207 | texts: 208 | en: >- 209 | On matters of style, the [style guide](http://google.github.io/styleguide/) 210 | is the absolute authority. Any purely style point (whitespace, etc.) that is 211 | not in the style guide is a matter of personal preference. The style should 212 | be consistent with what is there. If there is no previous style, accept the 213 | author's. 214 | ja: "スタイルに関しては、[スタイルガイド](http://google.github.io/styleguide/)が絶対的な権威である。スタイルガイドの記載のない純粋なスタイルの選択（空白をどうするかなど）は個人の好みの問題である。スタイルはシステム内で一貫している必要がある。スタイルの選択に前例がなければ、CL 作成者のやり方を受けれるべきである。" 215 | --- 216 | texts: 217 | en: >- 218 | **Aspects of software design are almost never a pure style issue or just a 219 | personal preference.** They are based on underlying principles and should be 220 | weighed on those principles, not simply by personal opinion. Sometimes there 221 | are a few valid options. If the author can demonstrate (either through data 222 | or based on solid engineering principles) that several approaches are 223 | equally valid, then the reviewer should accept the preference of the author. 224 | Otherwise the choice is dictated by standard principles of software design. 225 | ja: "ソフトウェア設計に関する論点はほとんどの場合、純粋なスタイルの問題でも個人的な好みの問題でもない。それは基本的な原則に基づいており、ただの個人的な意見によるのではなく、その原則に重点を置くべきである。有効な選択肢がいくつかある場合がある。複数の方法が同等に有効であると作成者が（データを示したり堅固な工学原理に基づいて説明したりして）証明できるとき、レビュアーは作成者の選好を受け入れるべきである。そうでない場合、選択はソフトウェア設計の標準的な原則によって決定される。" 226 | --- 227 | texts: 228 | en: >- 229 | If no other rule applies, then the reviewer may ask the author to be 230 | consistent with what is in the current codebase, as long as that doesn't 231 | worsen the overall code health of the system. 232 | ja: "他のルールが適用されない場合、システムのコードの全体的な健康状態を悪化させない限りは、レビュアーは CL 作成者に現在のコードベースとの一貫性を維持するよう求めることができる。" 233 | --- 234 | texts: 235 | en: Resolving Conflicts {#conflicts} 236 | ja: 意見の対立の解消 {#conflicts} 237 | --- 238 | texts: 239 | en: >- 240 | In any conflict on a code review, the first step should always be for the 241 | 242 | developer and reviewer to try to come to consensus, based on the contents of 243 | 244 | this document and the other documents in [The CL Author's Guide](../developer/) 245 | 246 | and this [Reviewer Guide](index.md). 247 | ja: >- 248 | コードレビューで意見の対立があれば、最初のステップで必ず行うべきは、このドキュメントと[CL 作成者のガイド](../developer/)、またこの[レビュアーガイド](index.md)の他のドキュメントに基づいて、開発者とレビュアーの間でコンセンサスが得られるように調整することです。 249 | --- 250 | texts: 251 | en: >- 252 | When coming to consensus becomes especially difficult, it can help to have a 253 | 254 | face-to-face meeting or a VC between the reviewer and the author, instead of 255 | 256 | just trying to resolve the conflict through code review comments. (If you do 257 | 258 | this, though, make sure to record the results of the discussion in a comment on 259 | 260 | the CL, for future readers.) 261 | ja: >- 262 | コンセンサスを得るのが特に難しいときには、レビュアーと作成者で対面でのミーティングやテレビ会議をもつほうが、コードレビューコメントのやり取りだけで対立を解消しようとするよりも効果がある場合があります。 263 | 264 | （対面でミーティングをするとしても、未来の読者のために CL のコメントにディスカッションの結果を記録するのを忘れないでください。） 265 | --- 266 | texts: 267 | en: >- 268 | If that doesn't resolve the situation, the most common way to resolve it would 269 | 270 | be to escalate. Often the 271 | 272 | escalation path is to a broader team discussion, having a TL weigh in, asking 273 | 274 | for a decision from a maintainer of the code, or asking an Eng Manager to help 275 | 276 | out. **Don't let a CL sit around because the author and the reviewer can't come 277 | 278 | to an agreement.** 279 | ja: >- 280 | それでも状況が変わらないなら、通例では、巻き込む人を増やすのが解決する方法です。 281 | 282 | よくあるのがより広範にチーム内で議論することです。TL に検討してもらったり、コードのメンテナーに決定してもらうようお願いしたり、技術マネージャーに助力を求めたりできます。 283 | 284 | **作成者とレビュアーが合意に達することができないからといって、CL をそのまま放置しないでください。** 285 | --- 286 | texts: 287 | en: "Next: [What to look for in a code review](looking-for.md)" 288 | ja: "次: [コードレビューの観点](looking-for.md)" 289 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "google-eng-practices-ja", 3 | "description": "Google Engineering Practices Documentation の日本語訳", 4 | "version": "1.0.0", 5 | "author": "Fuji Haruka (translator)", 6 | "bugs": { 7 | "url": "https://github.com/FujiHaruka/google-practices-ja/issues" 8 | }, 9 | "dependencies": { 10 | "inalz": "^0.11.0" 11 | }, 12 | "homepage": "https://fujiharuka.github.io/google-eng-practices-ja", 13 | "keywords": [], 14 | "license": "CC-By 3.0", 15 | "private": true, 16 | "repository": { 17 | "type": "git", 18 | "url": "git+https://github.com/FujiHaruka/google-practices-ja.git" 19 | }, 20 | "scripts": { 21 | "inalz": "inalz" 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /review/developer/cl-descriptions.md: -------------------------------------------------------------------------------- 1 | # Writing good CL descriptions 2 | 3 | 4 | 5 | A CL description is a public record of **what** change is being made and **why** 6 | it was made. It will become a permanent part of our version control history, and 7 | will possibly be read by hundreds of people other than your reviewers over the 8 | years. 9 | 10 | Future developers will search for your CL based on its description. Someone in 11 | the future might be looking for your change because of a faint memory of its 12 | relevance but without the specifics handy. If all the important information is 13 | in the code and not the description, it's going to be a lot harder for them to 14 | locate your CL. 15 | 16 | ## First Line {#firstline} 17 | 18 | * Short summary of what is being done. 19 | * Complete sentence, written as though it was an order. 20 | * Follow by empty line. 21 | 22 | The **first line** of a CL description should be a short summary of 23 | *specifically* **what** *is being done by the CL*, followed by a blank line. 24 | This is what most future code searchers will see when they are browsing the 25 | version control history of a piece of code, so this first line should be 26 | informative enough that they don't have to read your CL or its whole description 27 | just to get a general idea of what your CL actually *did*. 28 | 29 | By tradition, the first line of a CL description is a complete sentence, written 30 | as though it were an order (an imperative sentence). For example, say 31 | \"**Delete** the FizzBuzz RPC and **replace** it with the new system." instead 32 | of \"**Deleting** the FizzBuzz RPC and **replacing** it with the new system." 33 | You don't have to write the rest of the description as an imperative sentence, 34 | though. 35 | 36 | ## Body is Informative {#informative} 37 | 38 | The rest of the description should be informative. It might include a brief 39 | description of the problem that's being solved, and why this is the best 40 | approach. If there are any shortcomings to the approach, they should be 41 | mentioned. If relevant, include background information such as bug numbers, 42 | benchmark results, and links to design documents. 43 | 44 | Even small CLs deserve a little attention to detail. Put the CL in context. 45 | 46 | ## Bad CL Descriptions {#bad} 47 | 48 | "Fix bug" is an inadequate CL description. What bug? What did you do to fix it? 49 | Other similarly bad descriptions include: 50 | 51 | - "Fix build." 52 | - "Add patch." 53 | - "Moving code from A to B." 54 | - "Phase 1." 55 | - "Add convenience functions." 56 | - "kill weird URLs." 57 | 58 | Some of those are real CL descriptions. Their authors may believe they are 59 | providing useful information, but they are not serving the purpose of a CL 60 | description. 61 | 62 | ## Good CL Descriptions {#good} 63 | 64 | Here are some examples of good descriptions. 65 | 66 | ### Functionality change 67 | 68 | > rpc: remove size limit on RPC server message freelist. 69 | > 70 | > Servers like FizzBuzz have very large messages and would benefit from reuse. 71 | > Make the freelist larger, and add a goroutine that frees the freelist entries 72 | > slowly over time, so that idle servers eventually release all freelist 73 | > entries. 74 | 75 | The first few words describe what the CL actually does. The rest of the 76 | description talks about the problem being solved, why this is a good solution, 77 | and a bit more information about the specific implementation. 78 | 79 | ### Refactoring 80 | 81 | > Construct a Task with a TimeKeeper to use its TimeStr and Now methods. 82 | > 83 | > Add a Now method to Task, so the borglet() getter method can be removed (which 84 | > was only used by OOMCandidate to call borglet's Now method). This replaces the 85 | > methods on Borglet that delegate to a TimeKeeper. 86 | > 87 | > Allowing Tasks to supply Now is a step toward eliminating the dependency on 88 | > Borglet. Eventually, collaborators that depend on getting Now from the Task 89 | > should be changed to use a TimeKeeper directly, but this has been an 90 | > accommodation to refactoring in small steps. 91 | > 92 | > Continuing the long-range goal of refactoring the Borglet Hierarchy. 93 | 94 | The first line describes what the CL does and how this is a change from the 95 | past. The rest of the description talks about the specific implementation, the 96 | context of the CL, that the solution isn't ideal, and possible future direction. 97 | It also explains *why* this change is being made. 98 | 99 | ### Small CL that needs some context 100 | 101 | > Create a Python3 build rule for status.py. 102 | > 103 | > This allows consumers who are already using this as in Python3 to depend on a 104 | > rule that is next to the original status build rule instead of somewhere in 105 | > their own tree. It encourages new consumers to use Python3 if they can, 106 | > instead of Python2, and significantly simplifies some automated build file 107 | > refactoring tools being worked on currently. 108 | 109 | The first sentence describes what's actually being done. The rest of the 110 | description explains *why* the change is being made and gives the reviewer a lot 111 | of context. 112 | 113 | ## Review the description before submitting the CL 114 | 115 | CLs can undergo significant change during review. It can be worthwhile to review 116 | a CL description before submitting the CL, to ensure that the description still 117 | reflects what the CL does. 118 | 119 | Next: [Small CLs](small-cls.md) 120 | -------------------------------------------------------------------------------- /review/developer/handling-comments.md: -------------------------------------------------------------------------------- 1 | # How to handle reviewer comments 2 | 3 | 4 | 5 | When you've sent a CL out for review, it's likely that your reviewer will 6 | respond with several comments on your CL. Here are some useful things to know 7 | about handling reviewer comments. 8 | 9 | ## Don't Take it Personally {#personal} 10 | 11 | The goal of review is to maintain the quality of our codebase and our products. 12 | When a reviewer provides a critique of your code, think of it as their attempt 13 | to help you, the codebase, and Google, rather than as a personal attack on you 14 | or your abilities. 15 | 16 | Sometimes reviewers feel frustrated and they express that frustration in their 17 | comments. This isn't a good practice for reviewers, but as a developer you 18 | should be prepared for this. Ask yourself, "What is the constructive thing that 19 | the reviewer is trying to communicate to me?" and then operate as though that's 20 | what they actually said. 21 | 22 | **Never respond in anger to code review comments.** That is a serious breach of 23 | professional etiquette that will live forever in the code review tool. If you 24 | are too angry or annoyed to respond kindly, then walk away from your computer 25 | for a while, or work on something else until you feel calm enough to reply 26 | politely. 27 | 28 | In general, if a reviewer isn't providing feedback in a way that's constructive 29 | and polite, explain this to them in person. If you can't talk to them in person 30 | or on a video call, then send them a private email. Explain to them in a kind 31 | way what you don't like and what you'd like them to do differently. If they also 32 | respond in a non-constructive way to this private discussion, or it doesn't have 33 | the intended effect, then 34 | escalate to your manager as 35 | appropriate. 36 | 37 | ## Fix the Code {#code} 38 | 39 | If a reviewer says that they don't understand something in your code, your first 40 | response should be to clarify the code itself. If the code can't be clarified, 41 | add a code comment that explains why the code is there. If a comment seems 42 | pointless, only then should your response be an explanation in the code review 43 | tool. 44 | 45 | If a reviewer didn't understand some piece of your code, it's likely other 46 | future readers of the code won't understand either. Writing a response in the 47 | code review tool doesn't help future code readers, but clarifying your code or 48 | adding code comments does help them. 49 | 50 | ## Think for Yourself {#think} 51 | 52 | Writing a CL can take a lot of work. It's often really satisfying to finally 53 | send one out for review, feel like it's done, and be pretty sure that no further 54 | work is needed. So when a reviewer comes back with comments on things that could 55 | be improved, it's easy to reflexively think the comments are wrong, the reviewer 56 | is blocking you unnecessarily, or they should just let you submit the CL. 57 | However, **no matter how certain you are** at this point, take a moment to step 58 | back and consider if the reviewer is providing valuable feedback that will help 59 | the codebase and Google. Your first question to yourself should always be, "Is 60 | the reviewer correct?" 61 | 62 | If you can't answer that question, it's likely the reviewer needs to clarify 63 | their comments. 64 | 65 | If you *have* considered it and you still think you're right, feel free to 66 | respond with an explanation of why your method of doing things is better for the 67 | codebase, users, and/or Google. Often, reviewers are actually providing 68 | *suggestions* and they want you to think for yourself about what's best. You 69 | might actually know something about the users, codebase, or CL that the reviewer 70 | doesn't know. So fill them in; give them more context. Usually you can come to 71 | some consensus between yourself and the reviewer based on technical facts. 72 | 73 | ## Resolving Conflicts {#conflicts} 74 | 75 | Your first step in resolving conflicts should always be to try to come to 76 | consensus with your reviewer. If you can't achieve consensus, see 77 | [The Standard of Code Review](../reviewer/standard.md), which gives principles 78 | to follow in such a situation. 79 | -------------------------------------------------------------------------------- /review/developer/index.md: -------------------------------------------------------------------------------- 1 | # The CL author's guide to getting through code review 2 | 3 | The pages in this section contain best practices for developers going through 4 | code review. These guidelines should help you get through reviews faster and 5 | with higher-quality results. You don't have to read them all, but they are 6 | intended to apply to every Google developer, and many people have found it 7 | helpful to read the whole set. 8 | 9 | - [Writing Good CL Descriptions](cl-descriptions.md) 10 | - [Small CLs](small-cls.md) 11 | - [How to Handle Reviewer Comments](handling-comments.md) 12 | 13 | See also [How to Do a Code Review](../reviewer/), which gives detailed guidance 14 | for code reviewers. 15 | -------------------------------------------------------------------------------- /review/developer/small-cls.md: -------------------------------------------------------------------------------- 1 | # Small CLs 2 | 3 | 4 | 5 | ## Why Write Small CLs? {#why} 6 | 7 | Small, simple CLs are: 8 | 9 | - **Reviewed more quickly.** It's easier for a reviewer to find five minutes 10 | several times to review small CLs than to set aside a 30 minute block to 11 | review one large CL. 12 | - **Reviewed more thoroughly.** With large changes, reviewers and authors tend 13 | to get frustrated by large volumes of detailed commentary shifting back and 14 | forth—sometimes to the point where important points get missed or dropped. 15 | - **Less likely to introduce bugs.** Since you're making fewer changes, it's 16 | easier for you and your reviewer to reason effectively about the impact of 17 | the CL and see if a bug has been introduced. 18 | - **Less wasted work if they are rejected.** If you write a huge CL and then 19 | your reviewer says that the overall direction is wrong, you've wasted a lot 20 | of work. 21 | - **Easier to merge.** Working on a large CL takes a long time, so you will 22 | have lots of conflicts when you merge, and you will have to merge 23 | frequently. 24 | - **Easier to design well.** It's a lot easier to polish the design and code 25 | health of a small change than it is to refine all the details of a large 26 | change. 27 | - **Less blocking on reviews.** Sending self-contained portions of your 28 | overall change allows you to continue coding while you wait for your current 29 | CL in review. 30 | - **Simpler to roll back.** A large CL will more likely touch files that get 31 | updated between the initial CL submission and a rollback CL, complicating 32 | the rollback (the intermediate CLs will probably need to be rolled back 33 | too). 34 | 35 | Note that **reviewers have discretion to reject your change outright for the 36 | sole reason of it being too large.** Usually they will thank you for your 37 | contribution but request that you somehow make it into a series of smaller 38 | changes. It can be a lot of work to split up a change after you've already 39 | written it, or require lots of time arguing about why the reviewer should accept 40 | your large change. It's easier to just write small CLs in the first place. 41 | 42 | ## What is Small? {#what_is_small} 43 | 44 | In general, the right size for a CL is **one self-contained change**. This means 45 | that: 46 | 47 | - The CL makes a minimal change that addresses **just one thing**. This is 48 | usually just one part of a feature, rather than a whole feature at once. In 49 | general it's better to err on the side of writing CLs that are too small vs. 50 | CLs that are too large. Work with your reviewer to find out what an 51 | acceptable size is. 52 | - Everything the reviewer needs to understand about the CL (except future 53 | development) is in the CL, the CL's description, the existing codebase, or a 54 | CL they've already reviewed. 55 | - The system will continue to work well for its users and for the developers 56 | after the CL is checked in. 57 | - The CL is not so small that its implications are difficult to understand. If 58 | you add a new API, you should include a usage of the API in the same CL so 59 | that reviewers can better understand how the API will be used. This also 60 | prevents checking in unused APIs. 61 | 62 | There are no hard and fast rules about how large is "too large." 100 lines is 63 | usually a reasonable size for a CL, and 1000 lines is usually too large, but 64 | it's up to the judgment of your reviewer. The number of files that a change is 65 | spread across also affects its "size." A 200-line change in one file might be 66 | okay, but spread across 50 files it would usually be too large. 67 | 68 | Keep in mind that although you have been intimately involved with your code from 69 | the moment you started to write it, the reviewer often has no context. What 70 | seems like an acceptably-sized CL to you might be overwhelming to your reviewer. 71 | When in doubt, write CLs that are smaller than you think you need to write. 72 | Reviewers rarely complain about getting CLs that are too small. 73 | 74 | ## When are Large CLs Okay? {#large_okay} 75 | 76 | There are a few situations in which large changes aren't as bad: 77 | 78 | - You can usually count deletion of an entire file as being just one line of 79 | change, because it doesn't take the reviewer very long to review. 80 | - Sometimes a large CL has been generated by an automatic refactoring tool 81 | that you trust completely, and the reviewer's job is just to sanity check 82 | and say that they really do want the change. These CLs can be larger, 83 | although some of the caveats from above (such as merging and testing) still 84 | apply. 85 | 86 | ### Splitting by Files {#splitting-files} 87 | 88 | Another way to split up a CL is by groupings of files that will require 89 | different reviewers but are otherwise self-contained changes. 90 | 91 | For example: you send off one CL for modifications to a protocol buffer and 92 | another CL for changes to the code that uses that proto. You have to submit the 93 | proto CL before the code CL, but they can both be reviewed simultaneously. If 94 | you do this, you might want to inform both sets of reviewers about the other CL 95 | that you wrote, so that they have context for your changes. 96 | 97 | Another example: you send one CL for a code change and another for the 98 | configuration or experiment that uses that code; this is easier to roll back 99 | too, if necessary, as configuration/experiment files are sometimes pushed to 100 | production faster than code changes. 101 | 102 | ## Separate Out Refactorings {#refactoring} 103 | 104 | It's usually best to do refactorings in a separate CL from feature changes or 105 | bug fixes. For example, moving and renaming a class should be in a different CL 106 | from fixing a bug in that class. It is much easier for reviewers to understand 107 | the changes introduced by each CL when they are separate. 108 | 109 | Small cleanups such as fixing a local variable name can be included inside of a 110 | feature change or bug fix CL, though. It's up to the judgment of developers and 111 | reviewers to decide when a refactoring is so large that it will make the review 112 | more difficult if included in your current CL. 113 | 114 | ## Keep related test code in the same CL {#test_code} 115 | 116 | Avoid splitting test code into a separate CL. Tests validating your code 117 | modifications should go into the same CL, even if it increases the code line 118 | count. 119 | 120 | However, independent test modifications can go into separate CLs first, 121 | similar to the [refactorings guidelines](#refactoring). That includes: 122 | 123 | * validating pre-existing, submitted code with new tests. 124 | * refactoring the test code (e.g. introduce helper functions). 125 | * introducing larger test framework code (e.g. an integration test). 126 | 127 | ## Don't Break the Build {#break} 128 | 129 | If you have several CLs that depend on each other, you need to find a way to 130 | make sure the whole system keeps working after each CL is submitted. Otherwise 131 | you might break the build for all your fellow developers for a few minutes 132 | between your CL submissions (or even longer if something goes wrong unexpectedly 133 | with your later CL submissions). 134 | 135 | ## Can't Make it Small Enough {#cant} 136 | 137 | Sometimes you will encounter situations where it seems like your CL *has* to be 138 | large. This is very rarely true. Authors who practice writing small CLs can 139 | almost always find a way to decompose functionality into a series of small 140 | changes. 141 | 142 | Before writing a large CL, consider whether preceding it with a refactoring-only 143 | CL could pave the way for a cleaner implementation. Talk to your teammates and 144 | see if anybody has thoughts on how to implement the functionality in small CLs 145 | instead. 146 | 147 | If all of these options fail (which should be extremely rare) then get consent 148 | from your reviewers in advance to review a large CL, so they are warned about 149 | what is coming. In this situation, expect to be going through the review process 150 | for a long time, be vigilant about not introducing bugs, and be extra diligent 151 | about writing tests. 152 | 153 | Next: [How to Handle Reviewer Comments](handling-comments.md) 154 | -------------------------------------------------------------------------------- /review/emergencies.md: -------------------------------------------------------------------------------- 1 | # Emergencies 2 | 3 | Sometimes there are emergency CLs that must pass through the entire code review 4 | process as quickly as 5 | possible. 6 | 7 | 8 | 9 | ## What Is An Emergency? {#what} 10 | 11 | An emergency CL would be a **small** change that: allows a major launch to 12 | continue instead of rolling back, fixes a bug significantly affecting users in 13 | production, handles a pressing legal issue, closes a major security hole, etc. 14 | 15 | In emergencies we really do care about the speed of the entire code review 16 | process, not just the [speed of response](reviewer/speed.md). In this case 17 | *only*, the reviewer should care more about the speed of the review and the 18 | correctness of the code (does it actually resolve the emergency?) than anything 19 | else. Also (perhaps obviously) such reviews should take priority over all other 20 | code reviews, when they come up. 21 | 22 | However, after the emergency is resolved you should look over the emergency CLs 23 | again and give them a [more thorough review](reviewer/looking-for.md). 24 | 25 | ## What Is Not An Emergency? {#not} 26 | 27 | To be clear, the following cases are *not* an emergency: 28 | 29 | - Wanting to launch this week rather than next week (unless there is some 30 | actual [hard deadline](#deadlines) for launch such as a partner agreement). 31 | - The developer has worked on a feature for a very long time and they really 32 | want to get the CL in. 33 | - The reviewers are all in another timezone where it is currently nighttime or 34 | they are away on an off-site. 35 | - It is the end of the day on a Friday and it would just be great to get this 36 | CL in before the developer leaves for the weekend. 37 | - A manager says that this review has to be complete and the CL checked in 38 | today because of a [soft (not hard) deadline](#deadlines). 39 | - Rolling back a CL that is causing test failures or build breakages. 40 | 41 | And so on. 42 | 43 | ## What Is a Hard Deadline? {#deadlines} 44 | 45 | A hard deadline is one where **something disastrous would happen** if you miss 46 | it. For example: 47 | 48 | - Submitting your CL by a certain date is necessary for a contractual 49 | obligation. 50 | - Your product will completely fail in the marketplace if not released by a 51 | certain date. 52 | - Some hardware manufacturers only ship new hardware once a year. If you miss 53 | the deadline to submit code to them, that could be disastrous, depending on 54 | what type of code you’re trying to ship. 55 | 56 | Delaying a release for a week is not disastrous. Missing an important conference 57 | might be disastrous, but often is not. 58 | 59 | Most deadlines are soft deadlines, not hard deadlines. They represent a desire 60 | for a feature to be done by a certain time. They are important, but you 61 | shouldn’t be sacrificing code health to make them. 62 | 63 | If you have a long release cycle (several weeks) it can be tempting to sacrifice 64 | code review quality to get a feature in before the next cycle. However, this 65 | pattern, if repeated, is a common way for projects to build up overwhelming 66 | technical debt. If developers are routinely submitting CLs near the end of the 67 | cycle that "must get in" with only superficial review, then the team should 68 | modify its process so that large feature changes happen early in the cycle and 69 | have enough time for good review. 70 | -------------------------------------------------------------------------------- /review/index.md: -------------------------------------------------------------------------------- 1 | # Code Review Developer Guide 2 | 3 | ## Introduction {#intro} 4 | 5 | A code review is a process where someone other than the author(s) of a piece of 6 | code examines that code. 7 | 8 | At Google we use code review to maintain the quality of our code and products. 9 | 10 | This documentation is the canonical description of Google's code review 11 | processes and policies. 12 | 13 | 14 | 15 | This page is an overview of our code review process. There are two other large 16 | documents that are a part of this guide: 17 | 18 | - **[How To Do A Code Review](reviewer/)**: A detailed guide for code 19 | reviewers. 20 | - **[The CL Author's Guide](developer/)**: A detailed guide for developers 21 | whose CLs are going through review. 22 | 23 | ## What Do Code Reviewers Look For? {#look_for} 24 | 25 | Code reviews should look at: 26 | 27 | - **Design**: Is the code well-designed and appropriate for your system? 28 | - **Functionality**: Does the code behave as the author likely intended? Is 29 | the way the code behaves good for its users? 30 | - **Complexity**: Could the code be made simpler? Would another developer be 31 | able to easily understand and use this code when they come across it in the 32 | future? 33 | - **Tests**: Does the code have correct and well-designed automated tests? 34 | - **Naming**: Did the developer choose clear names for variables, classes, 35 | methods, etc.? 36 | - **Comments**: Are the comments clear and useful? 37 | - **Style**: Does the code follow our 38 | [style guides](http://google.github.io/styleguide/)? 39 | - **Documentation**: Did the developer also update relevant documentation? 40 | 41 | See **[How To Do A Code Review](reviewer/)** for more information. 42 | 43 | ### Picking the Best Reviewers {#best_reviewers} 44 | 45 | In general, you want to find the *best* reviewers you can who are capable of 46 | responding to your review within a reasonable period of time. 47 | 48 | The best reviewer is the person who will be able to give you the most thorough 49 | and correct review for the piece of code you are writing. This usually means the 50 | owner(s) of the code, who may or may not be the people in the OWNERS file. 51 | Sometimes this means asking different people to review different parts of the 52 | CL. 53 | 54 | If you find an ideal reviewer but they are not available, you should at least CC 55 | them on your change. 56 | 57 | ### In-Person Reviews {#in_person} 58 | 59 | If you pair-programmed a piece of code with somebody who was qualified to do a 60 | good code review on it, then that code is considered reviewed. 61 | 62 | You can also do in-person code reviews where the reviewer asks questions and the 63 | developer of the change speaks only when spoken to. 64 | 65 | ## See Also {#seealso} 66 | 67 | - [How To Do A Code Review](reviewer/): A detailed guide for code reviewers. 68 | - [The CL Author's Guide](developer/): A detailed guide for developers whose 69 | CLs are going through review. 70 | -------------------------------------------------------------------------------- /review/reviewer/comments.md: -------------------------------------------------------------------------------- 1 | # How to write code review comments 2 | 3 | 4 | 5 | ## Summary 6 | 7 | - Be kind. 8 | - Explain your reasoning. 9 | - Balance giving explicit directions with just pointing out problems and 10 | letting the developer decide. 11 | - Encourage developers to simplify code or add code comments instead of just 12 | explaining the complexity to you. 13 | 14 | ## Courtesy 15 | 16 | In general, it is important to be 17 | courteous and respectful while also being 18 | very clear and helpful to the developer whose code you are reviewing. One way to 19 | do this is to be sure that you are always making comments about the *code* and 20 | never making comments about the *developer*. You don't always have to follow 21 | this practice, but you should definitely use it when saying something that might 22 | otherwise be upsetting or contentious. For example: 23 | 24 | Bad: "Why did **you** use threads here when there's obviously no benefit to be 25 | gained from concurrency?" 26 | 27 | Good: "The concurrency model here is adding complexity to the system without any 28 | actual performance benefit that I can see. Because there's no performance 29 | benefit, it's best for this code to be single-threaded instead of using multiple 30 | threads." 31 | 32 | ## Explain Why {#why} 33 | 34 | One thing you'll notice about the "good" example from above is that it helps the 35 | developer understand *why* you are making your comment. You don't always need to 36 | include this information in your review comments, but sometimes it's appropriate 37 | to give a bit more explanation around your intent, the best practice you're 38 | following, or how your suggestion improves code health. 39 | 40 | ## Giving Guidance {#guidance} 41 | 42 | **In general it is the developer's responsibility to fix a CL, not the 43 | reviewer's.** You are not required to do detailed design of a solution or write 44 | code for the developer. 45 | 46 | This doesn't mean the reviewer should be unhelpful, though. In general you 47 | should strike an appropriate balance between pointing out problems and providing 48 | direct guidance. Pointing out problems and letting the developer make a decision 49 | often helps the developer learn, and makes it easier to do code reviews. It also 50 | can result in a better solution, because the developer is closer to the code 51 | than the reviewer is. 52 | 53 | However, sometimes direct instructions, suggestions, or even code are more 54 | helpful. The primary goal of code review is to get the best CL possible. A 55 | secondary goal is improving the skills of developers so that they require less 56 | and less review over time. 57 | 58 | ## Accepting Explanations {#explanations} 59 | 60 | If you ask a developer to explain a piece of code that you don't understand, 61 | that should usually result in them **rewriting the code more clearly**. 62 | Occasionally, adding a comment in the code is also an appropriate response, as 63 | long as it's not just explaining overly complex code. 64 | 65 | **Explanations written only in the code review tool are not helpful to future 66 | code readers.** They are acceptable only in a few circumstances, such as when 67 | you are reviewing an area you are not very familiar with and the developer 68 | explains something that normal readers of the code would have already known. 69 | 70 | Next: [Handling Pushback in Code Reviews](pushback.md) 71 | -------------------------------------------------------------------------------- /review/reviewer/index.md: -------------------------------------------------------------------------------- 1 | # How to do a code review 2 | 3 | The pages in this section contain recommendations on the best way to do code 4 | reviews, based on long experience. All together they represent one complete 5 | document, broken up into many separate sections. You don't have to read them 6 | all, but many people have found it very helpful to themselves and their team to 7 | read the entire set. 8 | 9 | - [The Standard of Code Review](standard.md) 10 | - [What to Look For In a Code Review](looking-for.md) 11 | - [Navigating a CL in Review](navigate.md) 12 | - [Speed of Code Reviews](speed.md) 13 | - [How to Write Code Review Comments](comments.md) 14 | - [Handling Pushback in Code Reviews](pushback.md) 15 | 16 | See also the [CL Author's Guide](../developer/), which gives detailed guidance 17 | to developers whose CLs are undergoing review. 18 | -------------------------------------------------------------------------------- /review/reviewer/looking-for.md: -------------------------------------------------------------------------------- 1 | # What to look for in a code review 2 | 3 | 4 | 5 | Note: Always make sure to take into account 6 | [The Standard of Code Review](standard.md) when considering each of these 7 | points. 8 | 9 | ## Design 10 | 11 | The most important thing to cover in a review is the overall design of the CL. 12 | Do the interactions of various pieces of code in the CL make sense? Does this 13 | change belong in your codebase, or in a library? Does it integrate well with the 14 | rest of your system? Is now a good time to add this functionality? 15 | 16 | ## Functionality 17 | 18 | Does this CL do what the developer intended? Is what the developer intended good 19 | for the users of this code? The "users" are usually both end-users (when they 20 | are affected by the change) and developers (who will have to "use" this code in 21 | the future). 22 | 23 | Mostly, we expect developers to test CLs well-enough that they work correctly by 24 | the time they get to code review. However, as the reviewer you should still be 25 | thinking about edge cases, looking for concurrency problems, trying to think 26 | like a user, and making sure that there are no bugs that you see just by reading 27 | the code. 28 | 29 | You *can* validate the CL if you want—the time when it's most important for a 30 | reviewer to check a CL's behavior is when it has a user-facing impact, such as a 31 | **UI change**. It's hard to understand how some changes will impact a user when 32 | you're just reading the code. For changes like that, you can have the developer 33 | give you a demo of the functionality if it's too inconvenient to patch in the CL 34 | and try it yourself. 35 | 36 | Another time when it's particularly important to think about functionality 37 | during a code review is if there is some sort of **parallel programming** going 38 | on in the CL that could theoretically cause deadlocks or race conditions. These 39 | sorts of issues are very hard to detect by just running the code and usually 40 | need somebody (both the developer and the reviewer) to think through them 41 | carefully to be sure that problems aren't being introduced. (Note that this is 42 | also a good reason not to use concurrency models where race conditions or 43 | deadlocks are possible—it can make it very complex to do code reviews or 44 | understand the code.) 45 | 46 | ## Complexity 47 | 48 | Is the CL more complex than it should be? Check this at every level of the 49 | CL—are individual lines too complex? Are functions too complex? Are classes too 50 | complex? "Too complex" usually means **"can't be understood quickly by code 51 | readers."** It can also mean **"developers are likely to introduce bugs when 52 | they try to call or modify this code."** 53 | 54 | A particular type of complexity is **over-engineering**, where developers have 55 | made the code more generic than it needs to be, or added functionality that 56 | isn't presently needed by the system. Reviewers should be especially vigilant 57 | about over-engineering. Encourage developers to solve the problem they know 58 | needs to be solved *now*, not the problem that the developer speculates *might* 59 | need to be solved in the future. The future problem should be solved once it 60 | arrives and you can see its actual shape and requirements in the physical 61 | universe. 62 | 63 | ## Tests 64 | 65 | Ask for unit, integration, or end-to-end 66 | tests as appropriate for the change. In general, tests should be added in the 67 | same CL as the production code unless the CL is handling an 68 | [emergency](../emergencies.md). 69 | 70 | Make sure that the tests in the CL are correct, sensible, and useful. Tests do 71 | not test themselves, and we rarely write tests for our tests—a human must ensure 72 | that tests are valid. 73 | 74 | Will the tests actually fail when the code is broken? If the code changes 75 | beneath them, will they start producing false positives? Does each test make 76 | simple and useful assertions? Are the tests separated appropriately between 77 | different test methods? 78 | 79 | Remember that tests are also code that has to be maintained. Don't accept 80 | complexity in tests just because they aren't part of the main binary. 81 | 82 | ## Naming 83 | 84 | Did the developer pick good names for everything? A good name is long enough to 85 | fully communicate what the item is or does, without being so long that it 86 | becomes hard to read. 87 | 88 | ## Comments 89 | 90 | Did the developer write clear comments in understandable English? Are all of the 91 | comments actually necessary? Usually comments are useful when they **explain 92 | why** some code exists, and should not be explaining *what* some code is doing. 93 | If the code isn't clear enough to explain itself, then the code should be made 94 | simpler. There are some exceptions (regular expressions and complex algorithms 95 | often benefit greatly from comments that explain what they're doing, for 96 | example) but mostly comments are for information that the code itself can't 97 | possibly contain, like the reasoning behind a decision. 98 | 99 | It can also be helpful to look at comments that were there before this CL. Maybe 100 | there is a TODO that can be removed now, a comment advising against this change 101 | being made, etc. 102 | 103 | Note that comments are different from *documentation* of classes, modules, or 104 | functions, which should instead express the purpose of a piece of code, how it 105 | should be used, and how it behaves when used. 106 | 107 | ## Style 108 | 109 | We have [style guides](http://google.github.io/styleguide/) at Google for all 110 | of our major languages, and even for most of the minor languages. Make sure the 111 | CL follows the appropriate style guides. 112 | 113 | If you want to improve some style point that isn't in the style guide, prefix 114 | your comment with "Nit:" to let the developer know that it's a nitpick that you 115 | think would improve the code but isn't mandatory. Don't block CLs from being 116 | submitted based only on personal style preferences. 117 | 118 | The author of the CL should not include major style changes combined with other 119 | changes. It makes it hard to see what is being changed in the CL, makes merges 120 | and rollbacks more complex, and causes other problems. For example, if the 121 | author wants to reformat the whole file, have them send you just the 122 | reformatting as one CL, and then send another CL with their functional changes 123 | after that. 124 | 125 | ## Documentation 126 | 127 | If a CL changes how users build, test, interact with, or release code, check to 128 | see that it also updates associated documentation, including 129 | READMEs, g3doc pages, and any generated 130 | reference docs. If the CL deletes or deprecates code, consider whether the 131 | documentation should also be deleted. 132 | If documentation is 133 | missing, ask for it. 134 | 135 | ## Every Line {#every_line} 136 | 137 | Look at *every* line of code that you have been assigned to review. Some things 138 | like data files, generated code, or large data structures you can scan over 139 | sometimes, but don't scan over a human-written class, function, or block of code 140 | and assume that what's inside of it is okay. Obviously some code deserves more 141 | careful scrutiny than other code—that's a judgment call that you have to 142 | make—but you should at least be sure that you *understand* what all the 143 | code is doing. 144 | 145 | If it's too hard for you to read the code and this is slowing down the review, 146 | then you should let the developer know that 147 | and wait for them to clarify it before you try to review it. At Google, we hire 148 | great software engineers, and you are one of them. If you can't understand the 149 | code, it's very likely that other developers won't either. So you're also 150 | helping future developers understand this code, when you ask the developer to 151 | clarify it. 152 | 153 | If you understand the code but you don't feel qualified to do some part of the 154 | review, make sure there is a reviewer on the CL who is qualified, particularly 155 | for complex issues such as security, concurrency, accessibility, 156 | internationalization, etc. 157 | 158 | ## Context 159 | 160 | It is often helpful to look at the CL in a broad context. Usually the code 161 | review tool will only show you a few lines of code around the parts that are 162 | being changed. Sometimes you have to look at the whole file to be sure that the 163 | change actually makes sense. For example, you might see only four new lines 164 | being added, but when you look at the whole file, you see those four lines are 165 | in a 50-line method that now really needs to be broken up into smaller methods. 166 | 167 | It's also useful to think about the CL in the context of the system as a whole. 168 | Is this CL improving the code health of the system or is it making the whole 169 | system more complex, less tested, etc.? **Don't accept CLs that degrade the code 170 | health of the system.** Most systems become complex through many small changes 171 | that add up, so it's important to prevent even small complexities in new 172 | changes. 173 | 174 | ## Good Things {#good_things} 175 | 176 | If you see something nice in the CL, tell the developer, especially when they 177 | addressed one of your comments in a great way. Code reviews often just focus on 178 | mistakes, but they should offer encouragement and appreciation for good 179 | practices, as well. It’s sometimes even more valuable, in terms of mentoring, to 180 | tell a developer what they did right than to tell them what they did wrong. 181 | 182 | ## Summary 183 | 184 | In doing a code review, you should make sure that: 185 | 186 | - The code is well-designed. 187 | - The functionality is good for the users of the code. 188 | - Any UI changes are sensible and look good. 189 | - Any parallel programming is done safely. 190 | - The code isn't more complex than it needs to be. 191 | - The developer isn't implementing things they *might* need in the future but 192 | don't know they need now. 193 | - Code has appropriate unit tests. 194 | - Tests are well-designed. 195 | - The developer used clear names for everything. 196 | - Comments are clear and useful, and mostly explain *why* instead of *what*. 197 | - Code is appropriately documented (generally in g3doc). 198 | - The code conforms to our style guides. 199 | 200 | Make sure to review **every line** of code you've been asked to review, look at 201 | the **context**, make sure you're **improving code health**, and compliment 202 | developers on **good things** that they do. 203 | 204 | Next: [Navigating a CL in Review](navigate.md) 205 | -------------------------------------------------------------------------------- /review/reviewer/navigate.md: -------------------------------------------------------------------------------- 1 | # Navigating a CL in review 2 | 3 | 4 | 5 | ## Summary 6 | 7 | Now that you know [what to look for](looking-for.md), what's the most efficient 8 | way to manage a review that's spread across multiple files? 9 | 10 | 1. Does the change make sense? Does it have a good 11 | [description](../developer/cl-descriptions.md)? 12 | 2. Look at the most important part of the change first. Is it well-designed 13 | overall? 14 | 3. Look at the rest of the CL in an appropriate sequence. 15 | 16 | ## Step One: Take a broad view of the change {#step_one} 17 | 18 | Look at the [CL description](../developer/cl-descriptions.md) and what the CL 19 | does in general. Does this change even make sense? If this change shouldn't have 20 | happened in the first place, please respond immediately with an explanation of 21 | why the change should not be happening. When you reject a change like this, it's 22 | also a good idea to suggest to the developer what they should have done instead. 23 | 24 | For example, you might say "Looks like you put some good work into this, thanks! 25 | However, we're actually going in the direction of removing the FooWidget system 26 | that you're modifying here, and so we don't want to make any new modifications 27 | to it right now. How about instead you refactor our new BarWidget class?" 28 | 29 | Note that not only did the reviewer reject the current CL and provide an 30 | alternative suggestion, but they did it *courteously*. This kind of courtesy is 31 | important because we want to show that we respect each other as developers even 32 | when we disagree. 33 | 34 | If you get more than a few CLs that represent changes you don't want to make, 35 | you should consider re-working your team's development process or the posted 36 | process for external contributors so that there is more communication before CLs 37 | are written. It's better to tell people "no" before they've done a ton of work 38 | that now has to be thrown away or drastically re-written. 39 | 40 | ## Step Two: Examine the main parts of the CL {#step_two} 41 | 42 | Find the file or files that are the "main" part of this CL. Often, there is one 43 | file that has the largest number of logical changes, and it's the major piece of 44 | the CL. Look at these major parts first. This helps give context to all of the 45 | smaller parts of the CL, and generally accelerates doing the code review. If the 46 | CL is too large for you to figure out which parts are the major parts, ask the 47 | developer what you should look at first, or ask them to 48 | [split up the CL into multiple CLs](../developer/small-cls.md). 49 | 50 | If you see some major design problems with this part of the CL, you should send 51 | those comments immediately, even if you don't have time to review the rest of 52 | the CL right now. In fact, reviewing the rest of the CL might be a waste of 53 | time, because if the design problems are significant enough, a lot of the other 54 | code under review is going to disappear and not matter anyway. 55 | 56 | There are two major reasons it's so important to send these major design 57 | comments out immediately: 58 | 59 | - Developers often mail a CL and then immediately start new work based on that 60 | CL while they wait for review. If there are major design problems in the CL 61 | you're reviewing, they're also going to have to re-work their later CL. You 62 | want to catch them before they've done too much extra work on top of the 63 | problematic design. 64 | - Major design changes take longer to do than small changes. Developers nearly 65 | all have deadlines; in order to make those deadlines and still have quality 66 | code in the codebase, the developer needs to start on any major re-work of 67 | the CL as soon as possible. 68 | 69 | ## Step Three: Look through the rest of the CL in an appropriate sequence {#step_three} 70 | 71 | Once you've confirmed there are no major design problems with the CL as a whole, 72 | try to figure out a logical sequence to look through the files while also making 73 | sure you don't miss reviewing any file. Usually after you've looked through the 74 | major files, it's simplest to just go through each file in the order that 75 | the code review tool presents them to you. Sometimes it's also helpful to read the tests 76 | first before you read the main code, because then you have an idea of what the 77 | change is supposed to be doing. 78 | 79 | Next: [Speed of Code Reviews](speed.md) 80 | -------------------------------------------------------------------------------- /review/reviewer/pushback.md: -------------------------------------------------------------------------------- 1 | # Handling pushback in code reviews 2 | 3 | 4 | 5 | Sometimes a developer will push back on a code review. Either they will disagree 6 | with your suggestion or they will complain that you are being too strict in 7 | general. 8 | 9 | ## Who is right? {#who_is_right} 10 | 11 | When a developer disagrees with your suggestion, first take a moment to consider 12 | if they are correct. Often, they are closer to the code than you are, and so 13 | they might really have a better insight about certain aspects of it. Does their 14 | argument make sense? Does it make sense from a code health perspective? If so, 15 | let them know that they are right and let the issue drop. 16 | 17 | However, developers are not always right. In this case the reviewer should 18 | further explain why they believe that their suggestion is correct. A good 19 | explanation demonstrates both an understanding of the developer's reply, and 20 | additional information about why the change is being requested. 21 | 22 | In particular, when the reviewer believes their suggestion will improve code 23 | health, they should continue to advocate for the change, if they believe the 24 | resulting code quality improvement justifies the additional work requested. 25 | **Improving code health tends to happen in small steps.** 26 | 27 | Sometimes it takes a few rounds of explaining a suggestion before it really 28 | sinks in. Just make sure to always stay [polite](comments.md#courtesy) and let 29 | the developer know that you *hear* what they're saying, you just don't *agree*. 30 | 31 | ## Upsetting Developers {#upsetting_developers} 32 | 33 | Reviewers sometimes believe that the developer will be upset if the reviewer 34 | insists on an improvement. Sometimes developers do become upset, but it is 35 | usually brief and they become very thankful later that you helped them improve 36 | the quality of their code. Usually, if you are [polite](comments.md#courtesy) in 37 | your comments, developers actually don't become upset at all, and the worry is 38 | just in the reviewer's mind. Upsets are usually more about 39 | [the way comments are written](comments.md#courtesy) than about the reviewer's 40 | insistence on code quality. 41 | 42 | ## Cleaning It Up Later {#later} 43 | 44 | A common source of push back is that developers (understandably) want to get 45 | things done. They don't want to go through another round of review just to get 46 | this CL in. So they say they will clean something up in a later CL, and thus you 47 | should LGTM *this* CL now. Some developers are very good about this, and will 48 | immediately write a follow-up CL that fixes the issue. However, experience shows 49 | that as more time passes after a developer writes the original CL, the less 50 | likely this clean up is to happen. In fact, usually unless the developer does 51 | the clean up *immediately* after the present CL, it never happens. This isn't 52 | because developers are irresponsible, but because they have a lot of work to do 53 | and the cleanup gets lost or forgotten in the press of other work. Thus, it is 54 | usually best to insist that the developer clean up their CL *now*, before the 55 | code is in the codebase and "done." Letting people "clean things up later" is a 56 | common way for codebases to degenerate. 57 | 58 | If a CL introduces new complexity, it must be cleaned up before submission 59 | unless it is an [emergency](../emergencies.md). If the CL exposes surrounding 60 | problems and they can't be addressed right now, the developer should file a bug 61 | for the cleanup and assign it to themselves so that it doesn't get lost. They 62 | can optionally also write a TODO comment in the code that references the filed 63 | bug. 64 | 65 | ## General Complaints About Strictness {#strictness} 66 | 67 | If you previously had fairly lax code reviews and you switch to having strict 68 | reviews, some developers will complain very loudly. Improving the 69 | [speed](speed.md) of your code reviews usually causes these complaints to fade 70 | away. 71 | 72 | Sometimes it can take months for these complaints to fade away, but eventually 73 | developers tend to see the value of strict code reviews as they see what great 74 | code they help generate. Sometimes the loudest protesters even become your 75 | strongest supporters once something happens that causes them to really see the 76 | value you're adding by being strict. 77 | 78 | ## Resolving Conflicts {#conflicts} 79 | 80 | If you are following all of the above but you still encounter a conflict between 81 | yourself and a developer that can't be resolved, see 82 | [The Standard of Code Review](standard.md) for guidelines and principles that 83 | can help resolve the conflict. 84 | -------------------------------------------------------------------------------- /review/reviewer/speed.md: -------------------------------------------------------------------------------- 1 | # Speed of Code Reviews 2 | 3 | 4 | 5 | ## Why Should Code Reviews Be Fast? {#why} 6 | 7 | **At Google, we optimize for the speed at which a team of developers can produce 8 | a product together**, as opposed to optimizing for the speed at which an 9 | individual developer can write code. The speed of individual development is 10 | important, it's just not _as_ important as the velocity of the entire team. 11 | 12 | When code reviews are slow, several things happen: 13 | 14 | * **The velocity of the team as a whole is decreased.** Yes, the individual, 15 | who doesn't respond quickly to the review, gets other work done. However, 16 | new features and bug fixes for the rest of the team are delayed by days, 17 | weeks, or months as each CL waits for review and re-review. 18 | * **Developers start to protest the code review process.** If a reviewer only 19 | responds every few days, but requests major changes to the CL each time, 20 | that can be frustrating and difficult for developers. Often, this is 21 | expressed as complaints about how "strict" the reviewer is being. If the 22 | reviewer requests the _same_ substantial changes (changes which really do 23 | improve code health) but responds _quickly_ every time the developer makes 24 | an update, the complaints tend to disappear. **Most complaints about the 25 | code review process are actually resolved by making the process faster.** 26 | * **Code health can be impacted.** When reviews are slow, there is increased 27 | pressure to allow developers to submit CLs that are not as good as they 28 | could be. Slow reviews also discourage code cleanups, refactorings, and 29 | further improvements to existing CLs. 30 | 31 | ## How Fast Should Code Reviews Be? {#fast} 32 | 33 | If you are not in the middle of a focused task, **you should do a code review 34 | shortly after it comes in.** 35 | 36 | **One business day is the maximum time it should take to respond** to a code 37 | review request (i.e. first thing the next morning). 38 | 39 | Following these guidelines means that a typical CL should get multiple rounds of 40 | review (if needed) within a single day. 41 | 42 | ## Speed vs. Interruption {#interruption} 43 | 44 | There is one time where the consideration of personal velocity trumps team 45 | velocity. **If you are in the middle of a focused task, such as writing code, 46 | don't interrupt yourself to do a code review.** Research has shown that it can 47 | take a long time for a developer to get back into a smooth flow of development 48 | after being interrupted. So interrupting yourself while coding is actually 49 | _more_ expensive to the team than making another developer wait a bit for a code 50 | review. 51 | 52 | Instead, wait for a break point in your work before you respond to a request for 53 | review. This could be when your current coding task is completed, after lunch, 54 | returning from a meeting, coming back from the microkitchen, etc. 55 | 56 | ## Fast Responses {#responses} 57 | 58 | When we talk about the speed of code reviews, it is the _response_ time that we 59 | are concerned with, as opposed to how long it takes a CL to get through the 60 | whole review and be submitted. The whole process should also be fast, ideally, 61 | but **it's even more important for the _individual responses_ to come quickly 62 | than it is for the whole process to happen rapidly.** 63 | 64 | Even if it sometimes takes a long time to get through the entire review 65 | _process_, having quick responses from the reviewer throughout the process 66 | significantly eases the frustration developers can feel with "slow" code 67 | reviews. 68 | 69 | If you are too busy to do a full review on a CL when it comes in, you can still 70 | send a quick response that lets the developer know when you will get to it, 71 | suggest other reviewers who might be able to respond more quickly, or 72 | [provide some initial broad comments](navigate.md). (Note: none of this means 73 | you should interrupt coding even to send a response like this—send the 74 | response at a reasonable break point in your work.) 75 | 76 | **It is important that reviewers spend enough time on review that they are 77 | certain their "LGTM" means "this code meets [our standards](standard.md)."** 78 | However, individual responses should still ideally be [fast](#fast). 79 | 80 | ## Cross-Time-Zone Reviews {#tz} 81 | 82 | When dealing with time zone differences, try to get back to the author when they 83 | are still in the office. If they have already gone home, then try to make sure 84 | your review is done before they get back to the office the next day. 85 | 86 | ## LGTM With Comments {#lgtm-with-comments} 87 | 88 | In order to speed up code reviews, there are certain situations in which a 89 | reviewer should give LGTM/Approval even though they are also leaving unresolved 90 | comments on the CL. This is done when either: 91 | 92 | * The reviewer is confident that the developer will appropriately address all 93 | the reviewer's remaining comments. 94 | * The remaining changes are minor and don't _have_ to be done by the 95 | developer. 96 | 97 | The reviewer should specify which of these options they intend, if it is not 98 | otherwise clear. 99 | 100 | LGTM With Comments is especially worth considering when the developer and 101 | reviewer are in different time zones and otherwise the developer would be 102 | waiting for a whole day just to get "LGTM, Approval." 103 | 104 | ## Large CLs {#large} 105 | 106 | If somebody sends you a code review that is so large you're not sure when you 107 | will be able to have time to review it, your typical response should be to ask 108 | the developer to 109 | [split the CL into several smaller CLs](../developer/small-cls.md) that build on 110 | each other, instead of one huge CL that has to be reviewed all at once. This is 111 | usually possible and very helpful to reviewers, even if it takes additional work 112 | from the developer. 113 | 114 | If a CL *can't* be broken up into smaller CLs, and you don't have time to review 115 | the entire thing quickly, then at least write some comments on the overall 116 | design of the CL and send it back to the developer for improvement. One of your 117 | goals as a reviewer should be to always unblock the developer or enable them to 118 | take some sort of further action quickly, without sacrificing code health to do 119 | so. 120 | 121 | ## Code Review Improvements Over Time {#time} 122 | 123 | If you follow these guidelines and you are strict with your code reviews, you 124 | should find that the entire code review process tends to go faster and faster 125 | over time. Developers learn what is required for healthy code, and send you CLs 126 | that are great from the start, requiring less and less review time. Reviewers 127 | learn to respond quickly and not add unnecessary latency into the review 128 | process. 129 | But **don't compromise on 130 | the [code review standards](standard.md) or quality for an imagined improvement 131 | in velocity**—it's not actually going to make anything happen more 132 | quickly, in the long run. 133 | 134 | ## Emergencies 135 | 136 | There are also [emergencies](../emergencies.md) where CLs must pass through the 137 | _whole_ review process very quickly, and where the quality guidelines would be 138 | relaxed. However, please see [What Is An Emergency?](../emergencies.md#what) for 139 | a description of which situations actually qualify as emergencies and which 140 | don't. 141 | 142 | Next: [How to Write Code Review Comments](comments.md) 143 | -------------------------------------------------------------------------------- /review/reviewer/standard.md: -------------------------------------------------------------------------------- 1 | # The Standard of Code Review 2 | 3 | 4 | 5 | The primary purpose of code review is to make sure that the overall 6 | code health of Google's code 7 | base is improving over time. All of the tools and processes of code review are 8 | designed to this end. 9 | 10 | In order to accomplish this, a series of trade-offs have to be balanced. 11 | 12 | First, developers must be able to _make progress_ on their tasks. If you never 13 | submit an improvement to the codebase, then the codebase never improves. Also, 14 | if a reviewer makes it very difficult for _any_ change to go in, then developers 15 | are disincentivized to make improvements in the future. 16 | 17 | On the other hand, it is the duty of the reviewer to make sure that each CL is 18 | of such a quality that the overall code health of their codebase is not 19 | decreasing as time goes on. This can be tricky, because often, codebases degrade 20 | through small decreases in code health over time, especially when a team is 21 | under significant time constraints and they feel that they have to take 22 | shortcuts in order to accomplish their goals. 23 | 24 | Also, a reviewer has ownership and responsibility over the code they are 25 | reviewing. They want to ensure that the codebase stays consistent, maintainable, 26 | and all of the other things mentioned in 27 | ["What to look for in a code review."](looking-for.md) 28 | 29 | Thus, we get the following rule as the standard we expect in code reviews: 30 | 31 | **In general, reviewers should favor approving a CL once it is in a state where 32 | it definitely improves the overall 33 | code health of the system 34 | being worked on, even if the CL isn't perfect.** 35 | 36 | That is _the_ senior principle among all of the code review guidelines. 37 | 38 | There are limitations to this, of course. For example, if a CL adds a feature 39 | that the reviewer doesn't want in their system, then the reviewer can certainly 40 | deny approval even if the code is well-designed. 41 | 42 | A key point here is that there is no such thing as "perfect" code—there is 43 | only _better_ code. Reviewers should not require the author to polish every tiny 44 | piece of a CL before granting approval. Rather, the reviewer should balance out 45 | the need to make forward progress compared to the importance of the changes they 46 | are suggesting. Instead of seeking perfection, what a reviewer should seek is 47 | _continuous improvement_. A CL that, as a whole, improves the maintainability, 48 | readability, and understandability of the system shouldn't be delayed for days 49 | or weeks because it isn't "perfect." 50 | 51 | Reviewers should _always_ feel free to leave comments expressing that something 52 | could be better, but if it's not very important, prefix it with something like 53 | "Nit: " to let the author know that it's just a point of polish that they could 54 | choose to ignore. 55 | 56 | Note: Nothing in this document justifies checking in CLs that definitely 57 | _worsen_ the overall code health of the system. The only time you would do that 58 | would be in an [emergency](../emergencies.md). 59 | 60 | ## Mentoring 61 | 62 | Code review can have an important function of teaching developers something new 63 | about a language, a framework, or general software design principles. It's 64 | always fine to leave comments that help a developer learn something new. Sharing 65 | knowledge is part of improving the code health of a system over time. Just keep 66 | in mind that if your comment is purely educational, but not critical to meeting 67 | the standards described in this document, prefix it with "Nit: " or otherwise 68 | indicate that it's not mandatory for the author to resolve it in this CL. 69 | 70 | ## Principles {#principles} 71 | 72 | * Technical facts and data overrule opinions and personal preferences. 73 | 74 | * On matters of style, the [style guide](http://google.github.io/styleguide/) 75 | is the absolute authority. Any purely style point (whitespace, etc.) that is 76 | not in the style guide is a matter of personal preference. The style should 77 | be consistent with what is there. If there is no previous style, accept the 78 | author's. 79 | 80 | * **Aspects of software design are almost never a pure style issue or just a 81 | personal preference.** They are based on underlying principles and should be 82 | weighed on those principles, not simply by personal opinion. Sometimes there 83 | are a few valid options. If the author can demonstrate (either through data 84 | or based on solid engineering principles) that several approaches are 85 | equally valid, then the reviewer should accept the preference of the author. 86 | Otherwise the choice is dictated by standard principles of software design. 87 | 88 | * If no other rule applies, then the reviewer may ask the author to be 89 | consistent with what is in the current codebase, as long as that doesn't 90 | worsen the overall code health of the system. 91 | 92 | ## Resolving Conflicts {#conflicts} 93 | 94 | In any conflict on a code review, the first step should always be for the 95 | developer and reviewer to try to come to consensus, based on the contents of 96 | this document and the other documents in [The CL Author's Guide](../developer/) 97 | and this [Reviewer Guide](index.md). 98 | 99 | When coming to consensus becomes especially difficult, it can help to have a 100 | face-to-face meeting or a VC between the reviewer and the author, instead of 101 | just trying to resolve the conflict through code review comments. (If you do 102 | this, though, make sure to record the results of the discussion in a comment on 103 | the CL, for future readers.) 104 | 105 | If that doesn't resolve the situation, the most common way to resolve it would 106 | be to escalate. Often the 107 | escalation path is to a broader team discussion, having a TL weigh in, asking 108 | for a decision from a maintainer of the code, or asking an Eng Manager to help 109 | out. **Don't let a CL sit around because the author and the reviewer can't come 110 | to an agreement.** 111 | 112 | Next: [What to look for in a code review](looking-for.md) 113 | --------------------------------------------------------------------------------