├── .github └── workflows │ └── jekyll-gh-pages.yml ├── LICENSE ├── README.md ├── _config.yml └── 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 /.github/workflows/jekyll-gh-pages.yml: -------------------------------------------------------------------------------- 1 | # Sample workflow for building and deploying a Jekyll site to GitHub Pages 2 | name: Deploy Jekyll with GitHub Pages dependencies preinstalled 3 | 4 | on: 5 | # Runs on pushes targeting the default branch 6 | push: 7 | branches: ["master"] 8 | 9 | # Allows you to run this workflow manually from the Actions tab 10 | workflow_dispatch: 11 | 12 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 13 | permissions: 14 | contents: read 15 | pages: write 16 | id-token: write 17 | 18 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. 19 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. 20 | concurrency: 21 | group: "pages" 22 | cancel-in-progress: false 23 | 24 | jobs: 25 | # Build job 26 | build: 27 | runs-on: ubuntu-latest 28 | steps: 29 | - name: Checkout 30 | uses: actions/checkout@v4 31 | - name: Setup Pages 32 | uses: actions/configure-pages@v5 33 | - name: Build with Jekyll 34 | uses: actions/jekyll-build-pages@v1 35 | with: 36 | source: ./ 37 | destination: ./_site 38 | - name: Upload artifact 39 | uses: actions/upload-pages-artifact@v3 40 | 41 | # Deployment job 42 | deploy: 43 | environment: 44 | name: github-pages 45 | url: ${{ steps.deployment.outputs.page_url }} 46 | runs-on: ubuntu-latest 47 | needs: build 48 | steps: 49 | - name: Deploy to GitHub Pages 50 | id: deployment 51 | uses: actions/deploy-pages@v4 52 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | Attribution 3.0 Unported 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR 10 | DAMAGES RESULTING FROM ITS USE. 11 | 12 | License 13 | 14 | THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE 15 | COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY 16 | COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS 17 | AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. 18 | 19 | BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE 20 | TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY 21 | BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS 22 | CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND 23 | CONDITIONS. 24 | 25 | 1. Definitions 26 | 27 | a. "Adaptation" means a work based upon the Work, or upon the Work and 28 | other pre-existing works, such as a translation, adaptation, 29 | derivative work, arrangement of music or other alterations of a 30 | literary or artistic work, or phonogram or performance and includes 31 | cinematographic adaptations or any other form in which the Work may be 32 | recast, transformed, or adapted including in any form recognizably 33 | derived from the original, except that a work that constitutes a 34 | Collection will not be considered an Adaptation for the purpose of 35 | this License. For the avoidance of doubt, where the Work is a musical 36 | work, performance or phonogram, the synchronization of the Work in 37 | timed-relation with a moving image ("synching") will be considered an 38 | Adaptation for the purpose of this License. 39 | b. "Collection" means a collection of literary or artistic works, such as 40 | encyclopedias and anthologies, or performances, phonograms or 41 | broadcasts, or other works or subject matter other than works listed 42 | in Section 1(f) below, which, by reason of the selection and 43 | arrangement of their contents, constitute intellectual creations, in 44 | which the Work is included in its entirety in unmodified form along 45 | with one or more other contributions, each constituting separate and 46 | independent works in themselves, which together are assembled into a 47 | collective whole. A work that constitutes a Collection will not be 48 | considered an Adaptation (as defined above) for the purposes of this 49 | License. 50 | c. "Distribute" means to make available to the public the original and 51 | copies of the Work or Adaptation, as appropriate, through sale or 52 | other transfer of ownership. 53 | d. "Licensor" means the individual, individuals, entity or entities that 54 | offer(s) the Work under the terms of this License. 55 | e. "Original Author" means, in the case of a literary or artistic work, 56 | the individual, individuals, entity or entities who created the Work 57 | or if no individual or entity can be identified, the publisher; and in 58 | addition (i) in the case of a performance the actors, singers, 59 | musicians, dancers, and other persons who act, sing, deliver, declaim, 60 | play in, interpret or otherwise perform literary or artistic works or 61 | expressions of folklore; (ii) in the case of a phonogram the producer 62 | being the person or legal entity who first fixes the sounds of a 63 | performance or other sounds; and, (iii) in the case of broadcasts, the 64 | organization that transmits the broadcast. 65 | f. "Work" means the literary and/or artistic work offered under the terms 66 | of this License including without limitation any production in the 67 | literary, scientific and artistic domain, whatever may be the mode or 68 | form of its expression including digital form, such as a book, 69 | pamphlet and other writing; a lecture, address, sermon or other work 70 | of the same nature; a dramatic or dramatico-musical work; a 71 | choreographic work or entertainment in dumb show; a musical 72 | composition with or without words; a cinematographic work to which are 73 | assimilated works expressed by a process analogous to cinematography; 74 | a work of drawing, painting, architecture, sculpture, engraving or 75 | lithography; a photographic work to which are assimilated works 76 | expressed by a process analogous to photography; a work of applied 77 | art; an illustration, map, plan, sketch or three-dimensional work 78 | relative to geography, topography, architecture or science; a 79 | performance; a broadcast; a phonogram; a compilation of data to the 80 | extent it is protected as a copyrightable work; or a work performed by 81 | a variety or circus performer to the extent it is not otherwise 82 | considered a literary or artistic work. 83 | g. "You" means an individual or entity exercising rights under this 84 | License who has not previously violated the terms of this License with 85 | respect to the Work, or who has received express permission from the 86 | Licensor to exercise rights under this License despite a previous 87 | violation. 88 | h. "Publicly Perform" means to perform public recitations of the Work and 89 | to communicate to the public those public recitations, by any means or 90 | process, including by wire or wireless means or public digital 91 | performances; to make available to the public Works in such a way that 92 | members of the public may access these Works from a place and at a 93 | place individually chosen by them; to perform the Work to the public 94 | by any means or process and the communication to the public of the 95 | performances of the Work, including by public digital performance; to 96 | broadcast and rebroadcast the Work by any means including signs, 97 | sounds or images. 98 | i. "Reproduce" means to make copies of the Work by any means including 99 | without limitation by sound or visual recordings and the right of 100 | fixation and reproducing fixations of the Work, including storage of a 101 | protected performance or phonogram in digital form or other electronic 102 | medium. 103 | 104 | 2. Fair Dealing Rights. Nothing in this License is intended to reduce, 105 | limit, or restrict any uses free from copyright or rights arising from 106 | limitations or exceptions that are provided for in connection with the 107 | copyright protection under copyright law or other applicable laws. 108 | 109 | 3. License Grant. Subject to the terms and conditions of this License, 110 | Licensor hereby grants You a worldwide, royalty-free, non-exclusive, 111 | perpetual (for the duration of the applicable copyright) license to 112 | exercise the rights in the Work as stated below: 113 | 114 | a. to Reproduce the Work, to incorporate the Work into one or more 115 | Collections, and to Reproduce the Work as incorporated in the 116 | Collections; 117 | b. to create and Reproduce Adaptations provided that any such Adaptation, 118 | including any translation in any medium, takes reasonable steps to 119 | clearly label, demarcate or otherwise identify that changes were made 120 | to the original Work. For example, a translation could be marked "The 121 | original work was translated from English to Spanish," or a 122 | modification could indicate "The original work has been modified."; 123 | c. to Distribute and Publicly Perform the Work including as incorporated 124 | in Collections; and, 125 | d. to Distribute and Publicly Perform Adaptations. 126 | e. For the avoidance of doubt: 127 | 128 | i. Non-waivable Compulsory License Schemes. In those jurisdictions in 129 | which the right to collect royalties through any statutory or 130 | compulsory licensing scheme cannot be waived, the Licensor 131 | reserves the exclusive right to collect such royalties for any 132 | exercise by You of the rights granted under this License; 133 | ii. Waivable Compulsory License Schemes. In those jurisdictions in 134 | which the right to collect royalties through any statutory or 135 | compulsory licensing scheme can be waived, the Licensor waives the 136 | exclusive right to collect such royalties for any exercise by You 137 | of the rights granted under this License; and, 138 | iii. Voluntary License Schemes. The Licensor waives the right to 139 | collect royalties, whether individually or, in the event that the 140 | Licensor is a member of a collecting society that administers 141 | voluntary licensing schemes, via that society, from any exercise 142 | by You of the rights granted under this License. 143 | 144 | The above rights may be exercised in all media and formats whether now 145 | known or hereafter devised. The above rights include the right to make 146 | such modifications as are technically necessary to exercise the rights in 147 | other media and formats. Subject to Section 8(f), all rights not expressly 148 | granted by Licensor are hereby reserved. 149 | 150 | 4. Restrictions. The license granted in Section 3 above is expressly made 151 | subject to and limited by the following restrictions: 152 | 153 | a. You may Distribute or Publicly Perform the Work only under the terms 154 | of this License. You must include a copy of, or the Uniform Resource 155 | Identifier (URI) for, this License with every copy of the Work You 156 | Distribute or Publicly Perform. You may not offer or impose any terms 157 | on the Work that restrict the terms of this License or the ability of 158 | the recipient of the Work to exercise the rights granted to that 159 | recipient under the terms of the License. You may not sublicense the 160 | Work. You must keep intact all notices that refer to this License and 161 | to the disclaimer of warranties with every copy of the Work You 162 | Distribute or Publicly Perform. When You Distribute or Publicly 163 | Perform the Work, You may not impose any effective technological 164 | measures on the Work that restrict the ability of a recipient of the 165 | Work from You to exercise the rights granted to that recipient under 166 | the terms of the License. This Section 4(a) applies to the Work as 167 | incorporated in a Collection, but this does not require the Collection 168 | apart from the Work itself to be made subject to the terms of this 169 | License. If You create a Collection, upon notice from any Licensor You 170 | must, to the extent practicable, remove from the Collection any credit 171 | as required by Section 4(b), as requested. If You create an 172 | Adaptation, upon notice from any Licensor You must, to the extent 173 | practicable, remove from the Adaptation any credit as required by 174 | Section 4(b), as requested. 175 | b. If You Distribute, or Publicly Perform the Work or any Adaptations or 176 | Collections, You must, unless a request has been made pursuant to 177 | Section 4(a), keep intact all copyright notices for the Work and 178 | provide, reasonable to the medium or means You are utilizing: (i) the 179 | name of the Original Author (or pseudonym, if applicable) if supplied, 180 | and/or if the Original Author and/or Licensor designate another party 181 | or parties (e.g., a sponsor institute, publishing entity, journal) for 182 | attribution ("Attribution Parties") in Licensor's copyright notice, 183 | terms of service or by other reasonable means, the name of such party 184 | or parties; (ii) the title of the Work if supplied; (iii) to the 185 | extent reasonably practicable, the URI, if any, that Licensor 186 | specifies to be associated with the Work, unless such URI does not 187 | refer to the copyright notice or licensing information for the Work; 188 | and (iv) , consistent with Section 3(b), in the case of an Adaptation, 189 | a credit identifying the use of the Work in the Adaptation (e.g., 190 | "French translation of the Work by Original Author," or "Screenplay 191 | based on original Work by Original Author"). The credit required by 192 | this Section 4 (b) may be implemented in any reasonable manner; 193 | provided, however, that in the case of a Adaptation or Collection, at 194 | a minimum such credit will appear, if a credit for all contributing 195 | authors of the Adaptation or Collection appears, then as part of these 196 | credits and in a manner at least as prominent as the credits for the 197 | other contributing authors. For the avoidance of doubt, You may only 198 | use the credit required by this Section for the purpose of attribution 199 | in the manner set out above and, by exercising Your rights under this 200 | License, You may not implicitly or explicitly assert or imply any 201 | connection with, sponsorship or endorsement by the Original Author, 202 | Licensor and/or Attribution Parties, as appropriate, of You or Your 203 | use of the Work, without the separate, express prior written 204 | permission of the Original Author, Licensor and/or Attribution 205 | Parties. 206 | c. Except as otherwise agreed in writing by the Licensor or as may be 207 | otherwise permitted by applicable law, if You Reproduce, Distribute or 208 | Publicly Perform the Work either by itself or as part of any 209 | Adaptations or Collections, You must not distort, mutilate, modify or 210 | take other derogatory action in relation to the Work which would be 211 | prejudicial to the Original Author's honor or reputation. Licensor 212 | agrees that in those jurisdictions (e.g. Japan), in which any exercise 213 | of the right granted in Section 3(b) of this License (the right to 214 | make Adaptations) would be deemed to be a distortion, mutilation, 215 | modification or other derogatory action prejudicial to the Original 216 | Author's honor and reputation, the Licensor will waive or not assert, 217 | as appropriate, this Section, to the fullest extent permitted by the 218 | applicable national law, to enable You to reasonably exercise Your 219 | right under Section 3(b) of this License (right to make Adaptations) 220 | but not otherwise. 221 | 222 | 5. Representations, Warranties and Disclaimer 223 | 224 | UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR 225 | OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY 226 | KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, 227 | INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, 228 | FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF 229 | LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, 230 | WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION 231 | OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. 232 | 233 | 6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE 234 | LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR 235 | ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES 236 | ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS 237 | BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 238 | 239 | 7. Termination 240 | 241 | a. This License and the rights granted hereunder will terminate 242 | automatically upon any breach by You of the terms of this License. 243 | Individuals or entities who have received Adaptations or Collections 244 | from You under this License, however, will not have their licenses 245 | terminated provided such individuals or entities remain in full 246 | compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will 247 | survive any termination of this License. 248 | b. Subject to the above terms and conditions, the license granted here is 249 | perpetual (for the duration of the applicable copyright in the Work). 250 | Notwithstanding the above, Licensor reserves the right to release the 251 | Work under different license terms or to stop distributing the Work at 252 | any time; provided, however that any such election will not serve to 253 | withdraw this License (or any other license that has been, or is 254 | required to be, granted under the terms of this License), and this 255 | License will continue in full force and effect unless terminated as 256 | stated above. 257 | 258 | 8. Miscellaneous 259 | 260 | a. Each time You Distribute or Publicly Perform the Work or a Collection, 261 | the Licensor offers to the recipient a license to the Work on the same 262 | terms and conditions as the license granted to You under this License. 263 | b. Each time You Distribute or Publicly Perform an Adaptation, Licensor 264 | offers to the recipient a license to the original Work on the same 265 | terms and conditions as the license granted to You under this License. 266 | c. If any provision of this License is invalid or unenforceable under 267 | applicable law, it shall not affect the validity or enforceability of 268 | the remainder of the terms of this License, and without further action 269 | by the parties to this agreement, such provision shall be reformed to 270 | the minimum extent necessary to make such provision valid and 271 | enforceable. 272 | d. No term or provision of this License shall be deemed waived and no 273 | breach consented to unless such waiver or consent shall be in writing 274 | and signed by the party to be charged with such waiver or consent. 275 | e. This License constitutes the entire agreement between the parties with 276 | respect to the Work licensed here. There are no understandings, 277 | agreements or representations with respect to the Work not specified 278 | here. Licensor shall not be bound by any additional provisions that 279 | may appear in any communication from You. This License may not be 280 | modified without the mutual written agreement of the Licensor and You. 281 | f. The rights granted under, and the subject matter referenced, in this 282 | License were drafted utilizing the terminology of the Berne Convention 283 | for the Protection of Literary and Artistic Works (as amended on 284 | September 28, 1979), the Rome Convention of 1961, the WIPO Copyright 285 | Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 286 | and the Universal Copyright Convention (as revised on July 24, 1971). 287 | These rights and subject matter take effect in the relevant 288 | jurisdiction in which the License terms are sought to be enforced 289 | according to the corresponding provisions of the implementation of 290 | those treaty provisions in the applicable national law. If the 291 | standard suite of rights granted under applicable copyright law 292 | includes additional rights not granted under this License, such 293 | additional rights are deemed to be included in the License; this 294 | License is not intended to restrict the license of any rights under 295 | applicable law. 296 | 297 | 298 | Creative Commons Notice 299 | 300 | Creative Commons is not a party to this License, and makes no warranty 301 | whatsoever in connection with the Work. Creative Commons will not be 302 | liable to You or any party on any legal theory for any damages 303 | whatsoever, including without limitation any general, special, 304 | incidental or consequential damages arising in connection to this 305 | license. Notwithstanding the foregoing two (2) sentences, if Creative 306 | Commons has expressly identified itself as the Licensor hereunder, it 307 | shall have all rights and obligations of Licensor. 308 | 309 | Except for the limited purpose of indicating to the public that the 310 | Work is licensed under the CCPL, Creative Commons does not authorize 311 | the use by either party of the trademark "Creative Commons" or any 312 | related trademark or logo of Creative Commons without the prior 313 | written consent of Creative Commons. Any permitted use will be in 314 | compliance with Creative Commons' then-current trademark usage 315 | guidelines, as may be published on its website or otherwise made 316 | available upon request from time to time. For the avoidance of doubt, 317 | this trademark restriction does not form part of this License. 318 | 319 | Creative Commons may be contacted at https://creativecommons.org/. -------------------------------------------------------------------------------- /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", "patch", or "pull-request". 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 30 | [CC-By 3.0 License](LICENSE), which encourages you to share these documents. See 31 | for more details. 32 | 33 | Creative Commons License 34 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-primer 2 | -------------------------------------------------------------------------------- /review/developer/cl-descriptions.md: -------------------------------------------------------------------------------- 1 | # Writing good CL descriptions 2 | 3 | 4 | 5 | A CL description is a public record of change, and it is important that it 6 | communicates: 7 | 8 | 1. **What** change is being made? This should summarize the major changes such 9 | that readers have a sense of what is being changed without needing to read 10 | the entire CL. 11 | 12 | 1. **Why** are these changes being made? What contexts did you have as an 13 | author when making this change? Were there decisions you made that aren't 14 | reflected in the source code? etc. 15 | 16 | The CL description will become a permanent part of our version control history 17 | and will possibly be read by hundreds of people over the years. 18 | 19 | Future developers will search for your CL based on its description. Someone in 20 | the future might be looking for your change because of a faint memory of its 21 | relevance but without the specifics handy. If all the important information is 22 | in the code and not the description, it's going to be a lot harder for them to 23 | locate your CL. 24 | 25 | And then, after they find the CL, will they be able to understand *why* the 26 | change was made? Reading source code may reveal what the software is doing but 27 | it may not reveal why it exists, which can make it harder for future developers 28 | to know whether they can move 29 | [Chesterton's fence](https://abseil.io/resources/swe-book/html/ch03.html#understand_context). 30 | 31 | A well-written CL description will help those future engineers -- sometimes, 32 | including yourself! 33 | 34 | ## First Line {#first-line} 35 | 36 | 37 | 38 | * Short summary of what is being done. 39 | * Complete sentence, written as though it was an order. 40 | * Follow by empty line. 41 | 42 | The **first line** of a CL description should be a short summary of 43 | *specifically* **what** *is being done by the CL*, followed by a blank line. 44 | This is what appears in version control history summaries, so it should be 45 | informative enough that future code searchers don't have to read your CL or its 46 | whole description to understand what your CL actually *did* or how it differs 47 | from other CLs. That is, the first line should stand alone, allowing readers to 48 | skim through code history much faster. 49 | 50 | Try to keep your first line short, focused, and to the point. The clarity and 51 | utility to the reader should be the top concern. 52 | 53 | By tradition, the first line of a CL description is a complete sentence, written 54 | as though it were an order (an imperative sentence). For example, say 55 | \"**Delete** the FizzBuzz RPC and **replace** it with the new system." instead 56 | of \"**Deleting** the FizzBuzz RPC and **replacing** it with the new system." 57 | You don't have to write the rest of the description as an imperative sentence, 58 | though. 59 | 60 | ## Body is Informative {#informative} 61 | 62 | The [first line](#first-line) should be a short, focused summary, while the rest 63 | of the description should fill in the details and include any supplemental 64 | information a reader needs to understand the changelist holistically. It might 65 | include a brief description of the problem that's being solved, and why this is 66 | the best approach. If there are any shortcomings to the approach, they should be 67 | mentioned. If relevant, include background information such as bug numbers, 68 | benchmark results, and links to design documents. 69 | 70 | If you include links to external resources consider that they may not be visible 71 | to future readers due to access restrictions or retention policies. Where 72 | possible include enough context for reviewers and future readers to understand 73 | the CL. 74 | 75 | Even small CLs deserve a little attention to detail. Put the CL in context. 76 | 77 | ## Bad CL Descriptions {#bad} 78 | 79 | "Fix bug" is an inadequate CL description. What bug? What did you do to fix it? 80 | Other similarly bad descriptions include: 81 | 82 | - "Fix build." 83 | - "Add patch." 84 | - "Moving code from A to B." 85 | - "Phase 1." 86 | - "Add convenience functions." 87 | - "kill weird URLs." 88 | 89 | Some of those are real CL descriptions. Although short, they do not provide 90 | enough useful information. 91 | 92 | ## Good CL Descriptions {#good} 93 | 94 | Here are some examples of good descriptions. 95 | 96 | ### Functionality change {#functionality-change} 97 | 98 | Example: 99 | 100 | > RPC: Remove size limit on RPC server message freelist. 101 | > 102 | > Servers like FizzBuzz have very large messages and would benefit from reuse. 103 | > Make the freelist larger, and add a goroutine that frees the freelist entries 104 | > slowly over time, so that idle servers eventually release all freelist 105 | > entries. 106 | 107 | The first few words describe what the CL actually does. The rest of the 108 | description talks about the problem being solved, why this is a good solution, 109 | and a bit more information about the specific implementation. 110 | 111 | ### Refactoring {#refactoring} 112 | 113 | Example: 114 | 115 | > Construct a Task with a TimeKeeper to use its TimeStr and Now methods. 116 | > 117 | > Add a Now method to Task, so the borglet() getter method can be removed (which 118 | > was only used by OOMCandidate to call borglet's Now method). This replaces the 119 | > methods on Borglet that delegate to a TimeKeeper. 120 | > 121 | > Allowing Tasks to supply Now is a step toward eliminating the dependency on 122 | > Borglet. Eventually, collaborators that depend on getting Now from the Task 123 | > should be changed to use a TimeKeeper directly, but this has been an 124 | > accommodation to refactoring in small steps. 125 | > 126 | > Continuing the long-range goal of refactoring the Borglet Hierarchy. 127 | 128 | The first line describes what the CL does and how this is a change from the 129 | past. The rest of the description talks about the specific implementation, the 130 | context of the CL, that the solution isn't ideal, and possible future direction. 131 | It also explains *why* this change is being made. 132 | 133 | ### Small CL that needs some context 134 | 135 | Example: 136 | 137 | > Create a Python3 build rule for status.py. 138 | > 139 | > This allows consumers who are already using this as in Python3 to depend on a 140 | > rule that is next to the original status build rule instead of somewhere in 141 | > their own tree. It encourages new consumers to use Python3 if they can, 142 | > instead of Python2, and significantly simplifies some automated build file 143 | > refactoring tools being worked on currently. 144 | 145 | The first sentence describes what's actually being done. The rest of the 146 | description explains *why* the change is being made and gives the reviewer a lot 147 | of context. 148 | 149 | ## Using tags {#tags} 150 | 151 | Tags are manually entered labels that can be used to categorize CLs. These may 152 | be supported by tools or just used by team convention. 153 | 154 | For example: 155 | 156 | - "[tag]" 157 | - "[a longer tag]" 158 | - "#tag" 159 | - "tag:" 160 | 161 | Using tags is optional. 162 | 163 | When adding tags, consider whether they should be in the [body](#informative) of 164 | the CL description or the [first line](#first-line). Limit the usage of tags in 165 | the first line, as this can obscure the content. 166 | 167 | Examples with and without tags: 168 | 169 | ``` {.good} 170 | // Tags are okay in the first line if kept short. 171 | [banana] Peel the banana before eating. 172 | 173 | // Tags can be inlined in content. 174 | Peel the #banana before eating. 175 | 176 | // Tags are optional. 177 | Peel the banana before eating. 178 | 179 | // Multiple tags are acceptable if kept short. 180 | #banana #apple: Assemble a fruit basket. 181 | 182 | // Tags can go anywhere in the CL description. 183 | > Assemble a fruit basket. 184 | > 185 | > #banana #apple 186 | ``` 187 | 188 | ``` {.bad} 189 | // Too many tags (or tags that are too long) overwhelm the first line. 190 | // 191 | // Instead, consider whether the tags can be moved into the description body 192 | // and/or shortened. 193 | [banana peeler factory factory][apple picking service] Assemble a fruit basket. 194 | ``` 195 | 196 | ## Generated CL descriptions 197 | 198 | Some CLs are generated by tools. Whenever possible, their descriptions should 199 | also follow the advice here. That is, their first line should be short, focused, 200 | and stand alone, and the CL description body should include informative details 201 | that help reviewers and future code searchers understand each CL's effect. 202 | 203 | ## Review the description before submitting the CL 204 | 205 | CLs can undergo significant change during review. It can be worthwhile to review 206 | a CL description before submitting the CL, to ensure that the description still 207 | reflects what the CL does. 208 | 209 | Next: [Small CLs](small-cls.md) 210 | -------------------------------------------------------------------------------- /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 Collaboratively {#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. It can be frustrating to receive comments asking for changes, 55 | especially if you don't agree with them. 56 | 57 | At times like this, take a moment to step back and consider if the reviewer is 58 | providing valuable feedback that will help the codebase and Google. Your first 59 | question to yourself should always be, "Do I understand what the reviewer is 60 | asking for?" 61 | 62 | If you can't answer that question, ask the reviewer for clarification. 63 | 64 | And then, if you understand the comments but disagree with them, it's important 65 | to think collaboratively, not combatively or defensively: 66 | 67 | ```txt {.bad} 68 | Bad: "No, I'm not going to do that." 69 | ``` 70 | 71 | ```txt {.good} 72 | Good: "I went with X because of [these pros/cons] with [these tradeoffs] 73 | My understanding is that using Y would be worse because of [these reasons]. 74 | Are you suggesting that Y better serves the original tradeoffs, that we should 75 | weigh the tradeoffs differently, or something else?" 76 | ``` 77 | 78 | Remember, 79 | **[courtesy and respect](https://chromium.googlesource.com/chromium/src/+/master/docs/cr_respect.md) 80 | should always be a first priority**. If you disagree with the reviewer, find 81 | ways to collaborate: ask for clarifications, discuss pros/cons, and provide 82 | explanations of why your method of doing things is better for the codebase, 83 | users, and/or Google. 84 | 85 | Sometimes, you might know something about the users, codebase, or CL that the 86 | reviewer doesn't know. [Fix the code](#code) where appropriate, and engage your 87 | reviewer in discussion, including giving them more context. Usually you can come 88 | to some consensus between yourself and the reviewer based on technical facts. 89 | 90 | ## Resolving Conflicts {#conflicts} 91 | 92 | Your first step in resolving conflicts should always be to try to come to 93 | consensus with your reviewer. If you can't achieve consensus, see 94 | [The Standard of Code Review](../reviewer/standard.md), which gives principles 95 | to follow in such a situation. 96 | -------------------------------------------------------------------------------- /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/index.md), which gives detailed 14 | guidance 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 | 45 | 46 | In general, the right size for a CL is **one self-contained change**. This means 47 | that: 48 | 49 | - The CL makes a minimal change that addresses **just one thing**. This is 50 | usually just one part of a feature, rather than a whole feature at once. In 51 | general it's better to err on the side of writing CLs that are too small vs. 52 | CLs that are too large. Work with your reviewer to find out what an 53 | acceptable size is. 54 | - The CL should [include related test code](#test_code). 55 | - Everything the reviewer needs to understand about the CL (except future 56 | development) is in the CL, the CL's description, the existing codebase, or a 57 | CL they've already reviewed. 58 | - The system will continue to work well for its users and for the developers 59 | after the CL is checked in. 60 | - The CL is not so small that its implications are difficult to understand. If 61 | you add a new API, you should include a usage of the API in the same CL so 62 | that reviewers can better understand how the API will be used. This also 63 | prevents checking in unused APIs. 64 | 65 | There are no hard and fast rules about how large is "too large." 100 lines is 66 | usually a reasonable size for a CL, and 1000 lines is usually too large, but 67 | it's up to the judgment of your reviewer. The number of files that a change is 68 | spread across also affects its "size." A 200-line change in one file might be 69 | okay, but spread across 50 files it would usually be too large. 70 | 71 | Keep in mind that although you have been intimately involved with your code from 72 | the moment you started to write it, the reviewer often has no context. What 73 | seems like an acceptably-sized CL to you might be overwhelming to your reviewer. 74 | When in doubt, write CLs that are smaller than you think you need to write. 75 | Reviewers rarely complain about getting CLs that are too small. 76 | 77 | ## When are Large CLs Okay? {#large-okay} 78 | 79 | 80 | 81 | There are a few situations in which large changes aren't as bad: 82 | 83 | - You can usually count deletion of an entire file as being just one line of 84 | change, because it doesn't take the reviewer very long to review. 85 | - Sometimes a large CL has been generated by an automatic refactoring tool 86 | that you trust completely, and the reviewer's job is just to verify and say 87 | that they really do want the change. These CLs can be larger, although some 88 | of the caveats from above (such as merging and testing) still apply. 89 | 90 | ## Writing Small CLs Efficiently {#efficiently} 91 | 92 | If you write a small CL and then you wait for your reviewer to approve it before 93 | you write your next CL, then you're going to waste a lot of time. So you want to 94 | find some way to work that won't block you while you're waiting for review. This 95 | could involve having multiple projects to work on simultaneously, finding 96 | reviewers who agree to be immediately available, doing in-person reviews, pair 97 | programming, or splitting your CLs in a way that allows you to continue working 98 | immediately. 99 | 100 | ## Splitting CLs {#splitting} 101 | 102 | When starting work that will have multiple CLs with potential dependencies among 103 | each other, it's often useful to think about how to split and organize those CLs 104 | at a high level before diving into coding. 105 | 106 | Besides making things easier for you as an author to manage and organize your 107 | CLs, it also makes things easier for your code reviewers, which in turn makes 108 | your code reviews more efficient. 109 | 110 | Here are some strategies for splitting work into different CLs. 111 | 112 | ### Stacking Multiple Changes on Top of Each Other {#stacking} 113 | 114 | One way to split up a CL without blocking yourself is to write one small CL, 115 | send it off for review, and then immediately start writing another CL *based* on 116 | the first CL. Most version control systems allow you to do this somehow. 117 | 118 | ### Splitting by Files {#splitting-files} 119 | 120 | Another way to split up a CL is by groupings of files that will require 121 | different reviewers but are otherwise self-contained changes. 122 | 123 | For example: you send off one CL for modifications to a protocol buffer and 124 | another CL for changes to the code that uses that proto. You have to submit the 125 | proto CL before the code CL, but they can both be reviewed simultaneously. If 126 | you do this, you might want to inform both sets of reviewers about the other CL 127 | that you wrote, so that they have context for your changes. 128 | 129 | Another example: you send one CL for a code change and another for the 130 | configuration or experiment that uses that code; this is easier to roll back 131 | too, if necessary, as configuration/experiment files are sometimes pushed to 132 | production faster than code changes. 133 | 134 | ### Splitting Horizontally {#splitting-horizontally} 135 | 136 | Consider creating shared code or stubs that help isolate changes between layers 137 | of the tech stack. This not only helps expedite development but also encourages 138 | abstraction between layers. 139 | 140 | For example: You created a calculator app with client, API, service, and data 141 | model layers. A shared proto signature can abstract the service and data model 142 | layers from each other. Similarly, an API stub can split the implementation of 143 | client code from service code and enable them to move forward independently. 144 | Similar ideas can also be applied to more granular function or class level 145 | abstractions. 146 | 147 | ### Splitting Vertically {#splitting-vertically} 148 | 149 | Orthogonal to the layered, horizontal approach, you can instead break down your 150 | code into smaller, full-stack, vertical features. Each of these features can be 151 | independent parallel implementation tracks. This enables some tracks to move 152 | forward while other tracks are awaiting review or feedback. 153 | 154 | Back to our calculator example from 155 | [Splitting Horizontally](#splitting-horizontally). You now want to support new 156 | operators, like multiplication and division. You could split this up by 157 | implementing multiplication and division as separate verticals or sub-features, 158 | even though they may have some overlap such as shared button styling or shared 159 | validation logic. 160 | 161 | ### Splitting Horizontally & Vertically {#splitting-grid} 162 | 163 | To take this a step further, you could combine these approaches and chart out an 164 | implementation plan like this, where each cell is its own standalone CL. 165 | Starting from the model (at the bottom) and working up to the client: 166 | 167 | | Layer | Feature: Multiplication | Feature: Division | 168 | | ------- | ------------------------- | ------------------------------- | 169 | | Client | Add button | Add button | 170 | | API | Add endpoint | Add endpoint | 171 | | Service | Implement transformations | Share transformation logic with | 172 | : : : multiplication : 173 | | Model | Add proto definition | Add proto definition | 174 | 175 | ## Separate Out Refactorings {#refactoring} 176 | 177 | It's usually best to do refactorings in a separate CL from feature changes or 178 | bug fixes. For example, moving and renaming a class should be in a different CL 179 | from fixing a bug in that class. It is much easier for reviewers to understand 180 | the changes introduced by each CL when they are separate. 181 | 182 | Small cleanups such as fixing a local variable name can be included inside of a 183 | feature change or bug fix CL, though. It's up to the judgment of developers and 184 | reviewers to decide when a refactoring is so large that it will make the review 185 | more difficult if included in your current CL. 186 | 187 | ## Keep related test code in the same CL {#test-code} 188 | 189 | 190 | 191 | CLs should include related test code. Remember that [smallness](#what-is-small) 192 | here refers the conceptual idea that the CL should be focused and is not a 193 | simplistic function on line count. 194 | 195 | Tests are expected for all Google changes. 196 | 197 | A CL that adds or changes logic should be accompanied by new or updated tests 198 | for the new behavior. Pure refactoring CLs (that aren't intended to change 199 | behavior) should also be covered by tests; ideally, these tests already exist, 200 | but if they don't, you should add them. 201 | 202 | *Independent* test modifications can go into separate CLs first, similar to the 203 | [refactorings guidelines](#refactoring). That includes: 204 | 205 | * Validating pre-existing, submitted code with new tests. 206 | * Ensures that important logic is covered by tests. 207 | * Increases confidence in subsequent refactorings on affected code. For 208 | example, if you want to refactor code that isn't already covered by 209 | tests, submitting test CLs *before* submitting refactoring CLs can 210 | validate that the tested behavior is unchanged before and after the 211 | refactoring. 212 | * Refactoring the test code (e.g. introduce helper functions). 213 | * Introducing larger test framework code (e.g. an integration test). 214 | 215 | ## Don't Break the Build {#break} 216 | 217 | If you have several CLs that depend on each other, you need to find a way to 218 | make sure the whole system keeps working after each CL is submitted. Otherwise 219 | you might break the build for all your fellow developers for a few minutes 220 | between your CL submissions (or even longer if something goes wrong unexpectedly 221 | with your later CL submissions). 222 | 223 | ## Can't Make it Small Enough {#cant} 224 | 225 | Sometimes you will encounter situations where it seems like your CL *has* to be 226 | large. This is very rarely true. Authors who practice writing small CLs can 227 | almost always find a way to decompose functionality into a series of small 228 | changes. 229 | 230 | Before writing a large CL, consider whether preceding it with a refactoring-only 231 | CL could pave the way for a cleaner implementation. Talk to your teammates and 232 | see if anybody has thoughts on how to implement the functionality in small CLs 233 | instead. 234 | 235 | If all of these options fail (which should be extremely rare) then get consent 236 | from your reviewers in advance to review a large CL, so they are warned about 237 | what is coming. In this situation, expect to be going through the review process 238 | for a long time, be vigilant about not introducing bugs, and be extra diligent 239 | about writing tests. 240 | 241 | Next: [How to Handle Reviewer Comments](handling-comments.md) 242 | -------------------------------------------------------------------------------- /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 | 2 | ## Introduction {#intro} 3 | 4 | A code review is a process where someone other than the author(s) of a piece of 5 | code examines that code. 6 | 7 | At Google, we use code review to maintain the quality of our code and products. 8 | 9 | This documentation is the canonical description of Google's code review 10 | processes and policies. 11 | 12 | 13 | 14 | This page is an overview of our code review process. There are two other large 15 | documents that are a part of this guide: 16 | 17 | - **[How To Do A Code Review](reviewer/index.md)**: A detailed guide for code 18 | reviewers. 19 | - **[The CL Author's Guide](developer/index.md)**: A detailed guide for 20 | developers whose CLs are going through review. 21 | 22 | ## What Do Code Reviewers Look For? {#look_for} 23 | 24 | Code reviews should look at: 25 | 26 | - **Design**: Is the code well-designed and appropriate for your system? 27 | - **Functionality**: Does the code behave as the author likely intended? Is 28 | the way the code behaves good for its users? 29 | - **Complexity**: Could the code be made simpler? Would another developer be 30 | able to easily understand and use this code when they come across it in the 31 | future? 32 | - **Tests**: Does the code have correct and well-designed automated tests? 33 | - **Naming**: Did the developer choose clear names for variables, classes, 34 | methods, etc.? 35 | - **Comments**: Are the comments clear and useful? 36 | - **Style**: Does the code follow our 37 | [style guides](http://google.github.io/styleguide/)? 38 | - **Documentation**: Did the developer also update relevant documentation? 39 | 40 | See **[How To Do A Code Review](reviewer/index.md)** for more information. 41 | 42 | ### Picking the Best Reviewers {#best_reviewers} 43 | 44 | In general, you want to find the *best* reviewers you can who are capable of 45 | responding to your review within a reasonable period of time. 46 | 47 | The best reviewer is the person who will be able to give you the most thorough 48 | and correct review for the piece of code you are writing. This usually means the 49 | owner(s) of the code, who may or may not be the people in the OWNERS file. 50 | Sometimes this means asking different people to review different parts of the 51 | CL. 52 | 53 | If you find an ideal reviewer but they are not available, you should at least CC 54 | them on your change. 55 | 56 | ### In-Person Reviews (and Pair Programming) {#in_person} 57 | 58 | If you pair-programmed a piece of code with somebody who was qualified to do a 59 | good code review on it, then that code is considered reviewed. 60 | 61 | You can also do in-person code reviews where the reviewer asks questions and the 62 | developer of the change speaks only when spoken to. 63 | 64 | ## See Also {#seealso} 65 | 66 | - [How To Do A Code Review](reviewer/index.md): A detailed guide for code 67 | reviewers. 68 | - [The CL Author's Guide](developer/index.md): A detailed guide for developers 69 | whose 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](https://chromium.googlesource.com/chromium/src/+/master/docs/cr_respect.md) 18 | while also being very clear and helpful to the developer whose code you are 19 | reviewing. One way to do this is to be sure that you are always making comments 20 | about the *code* and never making comments about the *developer*. You don't 21 | always have to follow this practice, but you should definitely use it when 22 | saying something that might 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 | Remember that people learn from reinforcement of what they are doing well and 59 | not just what they could do better. If you see things you like in the CL, 60 | comment on those too! Examples: developer cleaned up a messy algorithm, added 61 | exemplary test coverage, or you as the reviewer learned something from the CL. 62 | Just as with all comments, include [why](#why) you liked something, further 63 | encouraging the developer to continue good practices. 64 | 65 | ## Label comment severity {#label-comment-severity} 66 | 67 | Consider labeling the severity of your comments, differentiating required 68 | changes from guidelines or suggestions. 69 | 70 | Here are some examples: 71 | 72 | > Nit: This is a minor thing. Technically you should do it, but it won’t hugely 73 | > impact things. 74 | > 75 | > Optional (or Consider): I think this may be a good idea, but it’s not strictly 76 | > required. 77 | > 78 | > FYI: I don’t expect you to do this in this CL, but you may find this 79 | > interesting to think about for the future. 80 | 81 | This makes review intent explicit and helps authors prioritize the importance of 82 | various comments. It also helps avoid misunderstandings; for example, without 83 | comment labels, authors may interpret all comments as mandatory, even if some 84 | comments are merely intended to be informational or optional. 85 | 86 | ## Accepting Explanations {#explanations} 87 | 88 | If you ask a developer to explain a piece of code that you don't understand, 89 | that should usually result in them **rewriting the code more clearly**. 90 | Occasionally, adding a comment in the code is also an appropriate response, as 91 | long as it's not just explaining overly complex code. 92 | 93 | **Explanations written only in the code review tool are not helpful to future 94 | code readers.** They are acceptable only in a few circumstances, such as when 95 | you are reviewing an area you are not very familiar with and the developer 96 | explains something that normal readers of the code would have already known. 97 | 98 | Next: [Handling Pushback in Code Reviews](pushback.md) 99 | -------------------------------------------------------------------------------- /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/index.md), which gives detailed 17 | guidance 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 | ## Consistency 126 | 127 | What if the existing code is inconsistent with the style guide? Per our 128 | [code review principles](standard.md#principles), the style guide is the 129 | absolute authority: if something is required by the style guide, the CL should 130 | follow the guidelines. 131 | 132 | In some cases, the style guide makes recommendations rather than declaring 133 | requirements. In these cases, it's a judgment call whether the new code should 134 | be consistent with the recommendations or the surrounding code. Bias towards 135 | following the style guide unless the local inconsistency would be too confusing. 136 | 137 | If no other rule applies, the author should maintain consistency with the 138 | existing code. 139 | 140 | Either way, encourage the author to file a bug and add a TODO for cleaning up 141 | existing code. 142 | 143 | ## Documentation 144 | 145 | If a CL changes how users build, test, interact with, or release code, check to 146 | see that it also updates associated documentation, including 147 | READMEs, g3doc pages, and any generated 148 | reference docs. If the CL deletes or deprecates code, consider whether the 149 | documentation should also be deleted. 150 | If documentation is 151 | missing, ask for it. 152 | 153 | ## Every Line {#every-line} 154 | 155 | In the general case, look at *every* line of code that you have been assigned to 156 | review. Some things like data files, generated code, or large data structures 157 | you can scan over sometimes, but don't scan over a human-written class, 158 | function, or block of code and assume that what's inside of it is okay. 159 | Obviously some code deserves more careful scrutiny than other code—that's 160 | a judgment call that you have to make—but you should at least be sure that 161 | you *understand* what all the code is doing. 162 | 163 | If it's too hard for you to read the code and this is slowing down the review, 164 | then you should let the developer know that 165 | and wait for them to clarify it before you try to review it. At Google, we hire 166 | great software engineers, and you are one of them. If you can't understand the 167 | code, it's very likely that other developers won't either. So you're also 168 | helping future developers understand this code, when you ask the developer to 169 | clarify it. 170 | 171 | If you understand the code but you don't feel qualified to do some part of the 172 | review, [make sure there is a reviewer](#every-line-exceptions) on the CL who is 173 | qualified, particularly for complex issues such as privacy, security, 174 | concurrency, accessibility, internationalization, etc. 175 | 176 | ### Exceptions {#every-line-exceptions} 177 | 178 | What if it doesn't make sense for you to review every line? For example, you are 179 | one of multiple reviewers on a CL and may be asked: 180 | 181 | * To review only certain files that are part of a larger change. 182 | * To review only certain aspects of the CL, such as the high-level design, 183 | privacy or security implications, etc. 184 | 185 | In these cases, note in a comment which parts you reviewed. Prefer giving 186 | [LGTM with comments](speed.md#lgtm-with-comments) 187 | . 188 | 189 | If you instead wish to grant LGTM after confirming that other reviewers have 190 | reviewed other parts of the CL, note this explicitly in a comment to set 191 | expectations. Aim to [respond quickly](speed.md#responses) once the CL has 192 | reached the desired state. 193 | 194 | ## Context 195 | 196 | It is often helpful to look at the CL in a broad context. Usually the code 197 | review tool will only show you a few lines of code around the parts that are 198 | being changed. Sometimes you have to look at the whole file to be sure that the 199 | change actually makes sense. For example, you might see only four new lines 200 | being added, but when you look at the whole file, you see those four lines are 201 | in a 50-line method that now really needs to be broken up into smaller methods. 202 | 203 | It's also useful to think about the CL in the context of the system as a whole. 204 | Is this CL improving the code health of the system or is it making the whole 205 | system more complex, less tested, etc.? **Don't accept CLs that degrade the code 206 | health of the system.** Most systems become complex through many small changes 207 | that add up, so it's important to prevent even small complexities in new 208 | changes. 209 | 210 | ## Good Things {#good-things} 211 | 212 | If you see something nice in the CL, tell the developer, especially when they 213 | addressed one of your comments in a great way. Code reviews often just focus on 214 | mistakes, but they should offer encouragement and appreciation for good 215 | practices, as well. It’s sometimes even more valuable, in terms of mentoring, to 216 | tell a developer what they did right than to tell them what they did wrong. 217 | 218 | ## Summary 219 | 220 | In doing a code review, you should make sure that: 221 | 222 | - The code is well-designed. 223 | - The functionality is good for the users of the code. 224 | - Any UI changes are sensible and look good. 225 | - Any parallel programming is done safely. 226 | - The code isn't more complex than it needs to be. 227 | - The developer isn't implementing things they *might* need in the future but 228 | don't know they need now. 229 | - Code has appropriate unit tests. 230 | - Tests are well-designed. 231 | - The developer used clear names for everything. 232 | - Comments are clear and useful, and mostly explain *why* instead of *what*. 233 | - Code is appropriately documented (generally in g3doc). 234 | - The code conforms to our style guides. 235 | 236 | Make sure to review **every line** of code you've been asked to review, look at 237 | the **context**, make sure you're **improving code health**, and compliment 238 | developers on **good things** that they do. 239 | 240 | Next: [Navigating a CL in Review](navigate.md) 241 | -------------------------------------------------------------------------------- /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, new 16 | features and bug fixes for the rest of the team are delayed by days, weeks, 17 | 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.** 47 | Research has shown that it can 48 | take a long time for a developer to get back into a smooth flow of development 49 | after being interrupted. So interrupting yourself while coding is actually 50 | *more* expensive to the team than making another developer wait a bit for a code 51 | review. 52 | 53 | Instead, wait for a break point in your work before you respond to a request for 54 | review. This could be when your current coding task is completed, after lunch, 55 | returning from a meeting, coming back from the breakroom, etc. 56 | 57 | ## Fast Responses {#responses} 58 | 59 | When we talk about the speed of code reviews, it is the *response* time that we 60 | are concerned with, as opposed to how long it takes a CL to get through the 61 | whole review and be submitted. The whole process should also be fast, ideally, 62 | but **it's even more important for the *individual responses* to come quickly 63 | than it is for the whole process to happen rapidly.** 64 | 65 | Even if it sometimes takes a long time to get through the entire review 66 | *process*, having quick responses from the reviewer throughout the process 67 | significantly eases the frustration developers can feel with "slow" code 68 | reviews. 69 | 70 | If you are too busy to do a full review on a CL when it comes in, you can still 71 | send a quick response that lets the developer know when you will get to it, 72 | suggest other reviewers who might be able to respond more quickly, or 73 | [provide some initial broad comments](navigate.md). (Note: none of this means 74 | you should interrupt coding even to send a response like this—send the 75 | response at a reasonable break point in your work.) 76 | 77 | **It is important that reviewers spend enough time on review that they are 78 | certain their "LGTM" means "this code meets [our standards](standard.md)."** 79 | However, individual responses should still ideally be [fast](#fast). 80 | 81 | ## Cross-Time-Zone Reviews {#tz} 82 | 83 | When dealing with time zone differences, try to get back to the author while 84 | they have time to respond before the end of their working hours. If they have 85 | already finished work for the day, then try to make sure your review is done 86 | before they start work the next day. 87 | 88 | ## LGTM With Comments {#lgtm-with-comments} 89 | 90 | In order to speed up code reviews, there are certain situations in which a 91 | reviewer should give LGTM/Approval even though they are also leaving unresolved 92 | comments on the CL. This should be done when at least one of the following 93 | applies: 94 | 95 | * The reviewer is confident that the developer will appropriately address all 96 | the reviewer's remaining comments. 97 | * The comments don't *have* to be addressed by the developer. 98 | * The suggestions are minor, e.g. sort imports, fix a nearby typo, apply a 99 | suggested fix, remove an unused dep, etc. 100 | 101 | The reviewer should specify which of these options they intend, if it is not 102 | otherwise clear. 103 | 104 | LGTM With Comments is especially worth considering when the developer and 105 | reviewer are in different time zones and otherwise the developer would be 106 | waiting for a whole day just to get "LGTM, Approval". 107 | 108 | ## Large CLs {#large} 109 | 110 | If somebody sends you a code review that is so large you're not sure when you 111 | will be able to have time to review it, your typical response should be to ask 112 | the developer to 113 | [split the CL into several smaller CLs](../developer/small-cls.md) that build on 114 | each other, instead of one huge CL that has to be reviewed all at once. This is 115 | usually possible and very helpful to reviewers, even if it takes additional work 116 | from the developer. 117 | 118 | If a CL *can't* be broken up into smaller CLs, and you don't have time to review 119 | the entire thing quickly, then at least write some comments on the overall 120 | design of the CL and send it back to the developer for improvement. One of your 121 | goals as a reviewer should be to always unblock the developer or enable them to 122 | take some sort of further action quickly, without sacrificing code health to do 123 | so. 124 | 125 | ## Code Review Improvements Over Time {#time} 126 | 127 | If you follow these guidelines and you are strict with your code reviews, you 128 | should find that the entire code review process tends to go faster and faster 129 | over time. Developers learn what is required for healthy code, and send you CLs 130 | that are great from the start, requiring less and less review time. Reviewers 131 | learn to respond quickly and not add unnecessary latency into the review 132 | process. 133 | But **don't compromise on 134 | the [code review standards](standard.md) or quality for an imagined improvement 135 | in velocity**—it's not actually going to make anything happen more 136 | quickly, in the long run. 137 | 138 | ## Emergencies 139 | 140 | There are also [emergencies](../emergencies.md) where CLs must pass through the 141 | *whole* review process very quickly, and where the quality guidelines would be 142 | relaxed. However, please see [What Is An Emergency?](../emergencies.md#what) for 143 | a description of which situations actually qualify as emergencies and which 144 | don't. 145 | 146 | Next: [How to Write Code Review Comments](comments.md) 147 | -------------------------------------------------------------------------------- /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 97 | [The CL Author's Guide](../developer/index.md) and this 98 | [Reviewer Guide](index.md). 99 | 100 | When coming to consensus becomes especially difficult, it can help to have a 101 | face-to-face meeting or a video conference between the reviewer and the author, instead of 102 | just trying to resolve the conflict through code review comments. (If you do 103 | this, though, make sure to record the results of the discussion as a comment on 104 | the CL, for future readers.) 105 | 106 | If that doesn't resolve the situation, the most common way to resolve it would 107 | be to escalate. Often the 108 | escalation path is to a broader team discussion, having a Technical Lead weigh in, asking 109 | for a decision from a maintainer of the code, or asking an Eng Manager to help 110 | out. **Don't let a CL sit around because the author and the reviewer can't come 111 | to an agreement.** 112 | 113 | Next: [What to look for in a code review](looking-for.md) 114 | --------------------------------------------------------------------------------