[
  {
    "path": ".github/workflows/jekyll-gh-pages.yml",
    "content": "# Sample workflow for building and deploying a Jekyll site to GitHub Pages\nname: Deploy Jekyll with GitHub Pages dependencies preinstalled\n\non:\n  # Runs on pushes targeting the default branch\n  push:\n    branches: [\"master\"]\n\n  # Allows you to run this workflow manually from the Actions tab\n  workflow_dispatch:\n\n# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\n# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.\n# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.\nconcurrency:\n  group: \"pages\"\n  cancel-in-progress: false\n\njobs:\n  # Build job\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Setup Pages\n        uses: actions/configure-pages@v5\n      - name: Build with Jekyll\n        uses: actions/jekyll-build-pages@v1\n        with:\n          source: ./\n          destination: ./_site\n      - name: Upload artifact\n        uses: actions/upload-pages-artifact@v3\n\n  # Deployment job\n  deploy:\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n    runs-on: ubuntu-latest\n    needs: build\n    steps:\n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v4\n"
  },
  {
    "path": "LICENSE",
    "content": "Creative Commons Legal Code\n\nAttribution 3.0 Unported\n\n    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE\n    LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN\n    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS\n    INFORMATION ON AN \"AS-IS\" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES\n    REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR\n    DAMAGES RESULTING FROM ITS USE.\n\nLicense\n\nTHE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE\nCOMMONS PUBLIC LICENSE (\"CCPL\" OR \"LICENSE\"). THE WORK IS PROTECTED BY\nCOPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS\nAUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.\n\nBY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE\nTO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY\nBE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS\nCONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND\nCONDITIONS.\n\n1. Definitions\n\n a. \"Adaptation\" means a work based upon the Work, or upon the Work and\n    other pre-existing works, such as a translation, adaptation,\n    derivative work, arrangement of music or other alterations of a\n    literary or artistic work, or phonogram or performance and includes\n    cinematographic adaptations or any other form in which the Work may be\n    recast, transformed, or adapted including in any form recognizably\n    derived from the original, except that a work that constitutes a\n    Collection will not be considered an Adaptation for the purpose of\n    this License. For the avoidance of doubt, where the Work is a musical\n    work, performance or phonogram, the synchronization of the Work in\n    timed-relation with a moving image (\"synching\") will be considered an\n    Adaptation for the purpose of this License.\n b. \"Collection\" means a collection of literary or artistic works, such as\n    encyclopedias and anthologies, or performances, phonograms or\n    broadcasts, or other works or subject matter other than works listed\n    in Section 1(f) below, which, by reason of the selection and\n    arrangement of their contents, constitute intellectual creations, in\n    which the Work is included in its entirety in unmodified form along\n    with one or more other contributions, each constituting separate and\n    independent works in themselves, which together are assembled into a\n    collective whole. A work that constitutes a Collection will not be\n    considered an Adaptation (as defined above) for the purposes of this\n    License.\n c. \"Distribute\" means to make available to the public the original and\n    copies of the Work or Adaptation, as appropriate, through sale or\n    other transfer of ownership.\n d. \"Licensor\" means the individual, individuals, entity or entities that\n    offer(s) the Work under the terms of this License.\n e. \"Original Author\" means, in the case of a literary or artistic work,\n    the individual, individuals, entity or entities who created the Work\n    or if no individual or entity can be identified, the publisher; and in\n    addition (i) in the case of a performance the actors, singers,\n    musicians, dancers, and other persons who act, sing, deliver, declaim,\n    play in, interpret or otherwise perform literary or artistic works or\n    expressions of folklore; (ii) in the case of a phonogram the producer\n    being the person or legal entity who first fixes the sounds of a\n    performance or other sounds; and, (iii) in the case of broadcasts, the\n    organization that transmits the broadcast.\n f. \"Work\" means the literary and/or artistic work offered under the terms\n    of this License including without limitation any production in the\n    literary, scientific and artistic domain, whatever may be the mode or\n    form of its expression including digital form, such as a book,\n    pamphlet and other writing; a lecture, address, sermon or other work\n    of the same nature; a dramatic or dramatico-musical work; a\n    choreographic work or entertainment in dumb show; a musical\n    composition with or without words; a cinematographic work to which are\n    assimilated works expressed by a process analogous to cinematography;\n    a work of drawing, painting, architecture, sculpture, engraving or\n    lithography; a photographic work to which are assimilated works\n    expressed by a process analogous to photography; a work of applied\n    art; an illustration, map, plan, sketch or three-dimensional work\n    relative to geography, topography, architecture or science; a\n    performance; a broadcast; a phonogram; a compilation of data to the\n    extent it is protected as a copyrightable work; or a work performed by\n    a variety or circus performer to the extent it is not otherwise\n    considered a literary or artistic work.\n g. \"You\" means an individual or entity exercising rights under this\n    License who has not previously violated the terms of this License with\n    respect to the Work, or who has received express permission from the\n    Licensor to exercise rights under this License despite a previous\n    violation.\n h. \"Publicly Perform\" means to perform public recitations of the Work and\n    to communicate to the public those public recitations, by any means or\n    process, including by wire or wireless means or public digital\n    performances; to make available to the public Works in such a way that\n    members of the public may access these Works from a place and at a\n    place individually chosen by them; to perform the Work to the public\n    by any means or process and the communication to the public of the\n    performances of the Work, including by public digital performance; to\n    broadcast and rebroadcast the Work by any means including signs,\n    sounds or images.\n i. \"Reproduce\" means to make copies of the Work by any means including\n    without limitation by sound or visual recordings and the right of\n    fixation and reproducing fixations of the Work, including storage of a\n    protected performance or phonogram in digital form or other electronic\n    medium.\n\n2. Fair Dealing Rights. Nothing in this License is intended to reduce,\nlimit, or restrict any uses free from copyright or rights arising from\nlimitations or exceptions that are provided for in connection with the\ncopyright protection under copyright law or other applicable laws.\n\n3. License Grant. Subject to the terms and conditions of this License,\nLicensor hereby grants You a worldwide, royalty-free, non-exclusive,\nperpetual (for the duration of the applicable copyright) license to\nexercise the rights in the Work as stated below:\n\n a. to Reproduce the Work, to incorporate the Work into one or more\n    Collections, and to Reproduce the Work as incorporated in the\n    Collections;\n b. to create and Reproduce Adaptations provided that any such Adaptation,\n    including any translation in any medium, takes reasonable steps to\n    clearly label, demarcate or otherwise identify that changes were made\n    to the original Work. For example, a translation could be marked \"The\n    original work was translated from English to Spanish,\" or a\n    modification could indicate \"The original work has been modified.\";\n c. to Distribute and Publicly Perform the Work including as incorporated\n    in Collections; and,\n d. to Distribute and Publicly Perform Adaptations.\n e. For the avoidance of doubt:\n\n     i. Non-waivable Compulsory License Schemes. In those jurisdictions in\n        which the right to collect royalties through any statutory or\n        compulsory licensing scheme cannot be waived, the Licensor\n        reserves the exclusive right to collect such royalties for any\n        exercise by You of the rights granted under this License;\n    ii. Waivable Compulsory License Schemes. In those jurisdictions in\n        which the right to collect royalties through any statutory or\n        compulsory licensing scheme can be waived, the Licensor waives the\n        exclusive right to collect such royalties for any exercise by You\n        of the rights granted under this License; and,\n   iii. Voluntary License Schemes. The Licensor waives the right to\n        collect royalties, whether individually or, in the event that the\n        Licensor is a member of a collecting society that administers\n        voluntary licensing schemes, via that society, from any exercise\n        by You of the rights granted under this License.\n\nThe above rights may be exercised in all media and formats whether now\nknown or hereafter devised. The above rights include the right to make\nsuch modifications as are technically necessary to exercise the rights in\nother media and formats. Subject to Section 8(f), all rights not expressly\ngranted by Licensor are hereby reserved.\n\n4. Restrictions. The license granted in Section 3 above is expressly made\nsubject to and limited by the following restrictions:\n\n a. You may Distribute or Publicly Perform the Work only under the terms\n    of this License. You must include a copy of, or the Uniform Resource\n    Identifier (URI) for, this License with every copy of the Work You\n    Distribute or Publicly Perform. You may not offer or impose any terms\n    on the Work that restrict the terms of this License or the ability of\n    the recipient of the Work to exercise the rights granted to that\n    recipient under the terms of the License. You may not sublicense the\n    Work. You must keep intact all notices that refer to this License and\n    to the disclaimer of warranties with every copy of the Work You\n    Distribute or Publicly Perform. When You Distribute or Publicly\n    Perform the Work, You may not impose any effective technological\n    measures on the Work that restrict the ability of a recipient of the\n    Work from You to exercise the rights granted to that recipient under\n    the terms of the License. This Section 4(a) applies to the Work as\n    incorporated in a Collection, but this does not require the Collection\n    apart from the Work itself to be made subject to the terms of this\n    License. If You create a Collection, upon notice from any Licensor You\n    must, to the extent practicable, remove from the Collection any credit\n    as required by Section 4(b), as requested. If You create an\n    Adaptation, upon notice from any Licensor You must, to the extent\n    practicable, remove from the Adaptation any credit as required by\n    Section 4(b), as requested.\n b. If You Distribute, or Publicly Perform the Work or any Adaptations or\n    Collections, You must, unless a request has been made pursuant to\n    Section 4(a), keep intact all copyright notices for the Work and\n    provide, reasonable to the medium or means You are utilizing: (i) the\n    name of the Original Author (or pseudonym, if applicable) if supplied,\n    and/or if the Original Author and/or Licensor designate another party\n    or parties (e.g., a sponsor institute, publishing entity, journal) for\n    attribution (\"Attribution Parties\") in Licensor's copyright notice,\n    terms of service or by other reasonable means, the name of such party\n    or parties; (ii) the title of the Work if supplied; (iii) to the\n    extent reasonably practicable, the URI, if any, that Licensor\n    specifies to be associated with the Work, unless such URI does not\n    refer to the copyright notice or licensing information for the Work;\n    and (iv) , consistent with Section 3(b), in the case of an Adaptation,\n    a credit identifying the use of the Work in the Adaptation (e.g.,\n    \"French translation of the Work by Original Author,\" or \"Screenplay\n    based on original Work by Original Author\"). The credit required by\n    this Section 4 (b) may be implemented in any reasonable manner;\n    provided, however, that in the case of a Adaptation or Collection, at\n    a minimum such credit will appear, if a credit for all contributing\n    authors of the Adaptation or Collection appears, then as part of these\n    credits and in a manner at least as prominent as the credits for the\n    other contributing authors. For the avoidance of doubt, You may only\n    use the credit required by this Section for the purpose of attribution\n    in the manner set out above and, by exercising Your rights under this\n    License, You may not implicitly or explicitly assert or imply any\n    connection with, sponsorship or endorsement by the Original Author,\n    Licensor and/or Attribution Parties, as appropriate, of You or Your\n    use of the Work, without the separate, express prior written\n    permission of the Original Author, Licensor and/or Attribution\n    Parties.\n c. Except as otherwise agreed in writing by the Licensor or as may be\n    otherwise permitted by applicable law, if You Reproduce, Distribute or\n    Publicly Perform the Work either by itself or as part of any\n    Adaptations or Collections, You must not distort, mutilate, modify or\n    take other derogatory action in relation to the Work which would be\n    prejudicial to the Original Author's honor or reputation. Licensor\n    agrees that in those jurisdictions (e.g. Japan), in which any exercise\n    of the right granted in Section 3(b) of this License (the right to\n    make Adaptations) would be deemed to be a distortion, mutilation,\n    modification or other derogatory action prejudicial to the Original\n    Author's honor and reputation, the Licensor will waive or not assert,\n    as appropriate, this Section, to the fullest extent permitted by the\n    applicable national law, to enable You to reasonably exercise Your\n    right under Section 3(b) of this License (right to make Adaptations)\n    but not otherwise.\n\n5. Representations, Warranties and Disclaimer\n\nUNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR\nOFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY\nKIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE,\nINCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY,\nFITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF\nLATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS,\nWHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION\nOF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.\n\n6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE\nLAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR\nANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES\nARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS\nBEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.\n\n7. Termination\n\n a. This License and the rights granted hereunder will terminate\n    automatically upon any breach by You of the terms of this License.\n    Individuals or entities who have received Adaptations or Collections\n    from You under this License, however, will not have their licenses\n    terminated provided such individuals or entities remain in full\n    compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will\n    survive any termination of this License.\n b. Subject to the above terms and conditions, the license granted here is\n    perpetual (for the duration of the applicable copyright in the Work).\n    Notwithstanding the above, Licensor reserves the right to release the\n    Work under different license terms or to stop distributing the Work at\n    any time; provided, however that any such election will not serve to\n    withdraw this License (or any other license that has been, or is\n    required to be, granted under the terms of this License), and this\n    License will continue in full force and effect unless terminated as\n    stated above.\n\n8. Miscellaneous\n\n a. Each time You Distribute or Publicly Perform the Work or a Collection,\n    the Licensor offers to the recipient a license to the Work on the same\n    terms and conditions as the license granted to You under this License.\n b. Each time You Distribute or Publicly Perform an Adaptation, Licensor\n    offers to the recipient a license to the original Work on the same\n    terms and conditions as the license granted to You under this License.\n c. If any provision of this License is invalid or unenforceable under\n    applicable law, it shall not affect the validity or enforceability of\n    the remainder of the terms of this License, and without further action\n    by the parties to this agreement, such provision shall be reformed to\n    the minimum extent necessary to make such provision valid and\n    enforceable.\n d. No term or provision of this License shall be deemed waived and no\n    breach consented to unless such waiver or consent shall be in writing\n    and signed by the party to be charged with such waiver or consent.\n e. This License constitutes the entire agreement between the parties with\n    respect to the Work licensed here. There are no understandings,\n    agreements or representations with respect to the Work not specified\n    here. Licensor shall not be bound by any additional provisions that\n    may appear in any communication from You. This License may not be\n    modified without the mutual written agreement of the Licensor and You.\n f. The rights granted under, and the subject matter referenced, in this\n    License were drafted utilizing the terminology of the Berne Convention\n    for the Protection of Literary and Artistic Works (as amended on\n    September 28, 1979), the Rome Convention of 1961, the WIPO Copyright\n    Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996\n    and the Universal Copyright Convention (as revised on July 24, 1971).\n    These rights and subject matter take effect in the relevant\n    jurisdiction in which the License terms are sought to be enforced\n    according to the corresponding provisions of the implementation of\n    those treaty provisions in the applicable national law. If the\n    standard suite of rights granted under applicable copyright law\n    includes additional rights not granted under this License, such\n    additional rights are deemed to be included in the License; this\n    License is not intended to restrict the license of any rights under\n    applicable law.\n\n\nCreative Commons Notice\n\n    Creative Commons is not a party to this License, and makes no warranty\n    whatsoever in connection with the Work. Creative Commons will not be\n    liable to You or any party on any legal theory for any damages\n    whatsoever, including without limitation any general, special,\n    incidental or consequential damages arising in connection to this\n    license. Notwithstanding the foregoing two (2) sentences, if Creative\n    Commons has expressly identified itself as the Licensor hereunder, it\n    shall have all rights and obligations of Licensor.\n\n    Except for the limited purpose of indicating to the public that the\n    Work is licensed under the CCPL, Creative Commons does not authorize\n    the use by either party of the trademark \"Creative Commons\" or any\n    related trademark or logo of Creative Commons without the prior\n    written consent of Creative Commons. Any permitted use will be in\n    compliance with Creative Commons' then-current trademark usage\n    guidelines, as may be published on its website or otherwise made\n    available upon request from time to time. For the avoidance of doubt,\n    this trademark restriction does not form part of this License.\n\n    Creative Commons may be contacted at https://creativecommons.org/."
  },
  {
    "path": "README.md",
    "content": "# Google Engineering Practices Documentation\n\nGoogle has many generalized engineering practices that cover all languages and\nall projects. These documents represent our collective experience of various\nbest practices that we have developed over time. It is possible that open source\nprojects or other organizations would benefit from this knowledge, so we work to\nmake it available publicly when possible.\n\nCurrently this contains the following documents:\n\n*   [Google's Code Review Guidelines](review/index.md), which are actually two\n    separate sets of documents:\n    *   [The Code Reviewer's Guide](review/reviewer/index.md)\n    *   [The Change Author's Guide](review/developer/index.md)\n\n## Terminology\n\nThere is some Google-internal terminology used in some of these documents, which\nwe clarify here for external readers:\n\n*   **CL**: Stands for \"changelist\", which means one self-contained change that\n    has been submitted to version control or which is undergoing code review.\n    Other organizations often call this a \"change\", \"patch\", or \"pull-request\".\n*   **LGTM**: Means \"Looks Good to Me\". It is what a code reviewer says when\n    approving a CL.\n\n## License\n\nThe documents in this project are licensed under the\n[CC-By 3.0 License](LICENSE), which encourages you to share these documents. See\n<https://creativecommons.org/licenses/by/3.0/> for more details.\n\n<a rel=\"license\" href=\"https://creativecommons.org/licenses/by/3.0/\"><img alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by/3.0/88x31.png\" /></a>\n"
  },
  {
    "path": "_config.yml",
    "content": "theme: jekyll-theme-primer\n"
  },
  {
    "path": "review/developer/cl-descriptions.md",
    "content": "# Writing good CL descriptions\n\n\n\nA CL description is a public record of change, and it is important that it\ncommunicates:\n\n1.  **What** change is being made? This should summarize the major changes such\n    that readers have a sense of what is being changed without needing to read\n    the entire CL.\n\n1.  **Why** are these changes being made? What contexts did you have as an\n    author when making this change? Were there decisions you made that aren't\n    reflected in the source code? etc.\n\nThe CL description will become a permanent part of our version control history\nand will possibly be read by hundreds of people over the years.\n\nFuture developers will search for your CL based on its description. Someone in\nthe future might be looking for your change because of a faint memory of its\nrelevance but without the specifics handy. If all the important information is\nin the code and not the description, it's going to be a lot harder for them to\nlocate your CL.\n\nAnd then, after they find the CL, will they be able to understand *why* the\nchange was made? Reading source code may reveal what the software is doing but\nit may not reveal why it exists, which can make it harder for future developers\nto know whether they can move\n[Chesterton's fence](https://abseil.io/resources/swe-book/html/ch03.html#understand_context).\n\nA well-written CL description will help those future engineers -- sometimes,\nincluding yourself!\n\n## First Line {#first-line}\n\n<a id=\"firstline\"></a> <!-- Keep previous permalink to avoid breaking old links. -->\n\n*   Short summary of what is being done.\n*   Complete sentence, written as though it was an order.\n*   Follow by empty line.\n\nThe **first line** of a CL description should be a short summary of\n*specifically* **what** *is being done by the CL*, followed by a blank line.\nThis is what appears in version control history summaries, so it should be\ninformative enough that future code searchers don't have to read your CL or its\nwhole description to understand what your CL actually *did* or how it differs\nfrom other CLs. That is, the first line should stand alone, allowing readers to\nskim through code history much faster.\n\nTry to keep your first line short, focused, and to the point. The clarity and\nutility to the reader should be the top concern.\n\nBy tradition, the first line of a CL description is a complete sentence, written\nas though it were an order (an imperative sentence). For example, say\n\\\"**Delete** the FizzBuzz RPC and **replace** it with the new system.\" instead\nof \\\"**Deleting** the FizzBuzz RPC and **replacing** it with the new system.\"\nYou don't have to write the rest of the description as an imperative sentence,\nthough.\n\n## Body is Informative {#informative}\n\nThe [first line](#first-line) should be a short, focused summary, while the rest\nof the description should fill in the details and include any supplemental\ninformation a reader needs to understand the changelist holistically. It might\ninclude a brief description of the problem that's being solved, and why this is\nthe best approach. If there are any shortcomings to the approach, they should be\nmentioned. If relevant, include background information such as bug numbers,\nbenchmark results, and links to design documents.\n\nIf you include links to external resources consider that they may not be visible\nto future readers due to access restrictions or retention policies. Where\npossible include enough context for reviewers and future readers to understand\nthe CL.\n\nEven small CLs deserve a little attention to detail. Put the CL in context.\n\n## Bad CL Descriptions {#bad}\n\n\"Fix bug\" is an inadequate CL description. What bug? What did you do to fix it?\nOther similarly bad descriptions include:\n\n-   \"Fix build.\"\n-   \"Add patch.\"\n-   \"Moving code from A to B.\"\n-   \"Phase 1.\"\n-   \"Add convenience functions.\"\n-   \"kill weird URLs.\"\n\nSome of those are real CL descriptions. Although short, they do not provide\nenough useful information.\n\n## Good CL Descriptions {#good}\n\nHere are some examples of good descriptions.\n\n### Functionality change {#functionality-change}\n\nExample:\n\n> RPC: Remove size limit on RPC server message freelist.\n>\n> Servers like FizzBuzz have very large messages and would benefit from reuse.\n> Make the freelist larger, and add a goroutine that frees the freelist entries\n> slowly over time, so that idle servers eventually release all freelist\n> entries.\n\nThe first few words describe what the CL actually does. The rest of the\ndescription talks about the problem being solved, why this is a good solution,\nand a bit more information about the specific implementation.\n\n### Refactoring {#refactoring}\n\nExample:\n\n> Construct a Task with a TimeKeeper to use its TimeStr and Now methods.\n>\n> Add a Now method to Task, so the borglet() getter method can be removed (which\n> was only used by OOMCandidate to call borglet's Now method). This replaces the\n> methods on Borglet that delegate to a TimeKeeper.\n>\n> Allowing Tasks to supply Now is a step toward eliminating the dependency on\n> Borglet. Eventually, collaborators that depend on getting Now from the Task\n> should be changed to use a TimeKeeper directly, but this has been an\n> accommodation to refactoring in small steps.\n>\n> Continuing the long-range goal of refactoring the Borglet Hierarchy.\n\nThe first line describes what the CL does and how this is a change from the\npast. The rest of the description talks about the specific implementation, the\ncontext of the CL, that the solution isn't ideal, and possible future direction.\nIt also explains *why* this change is being made.\n\n### Small CL that needs some context\n\nExample:\n\n> Create a Python3 build rule for status.py.\n>\n> This allows consumers who are already using this as in Python3 to depend on a\n> rule that is next to the original status build rule instead of somewhere in\n> their own tree. It encourages new consumers to use Python3 if they can,\n> instead of Python2, and significantly simplifies some automated build file\n> refactoring tools being worked on currently.\n\nThe first sentence describes what's actually being done. The rest of the\ndescription explains *why* the change is being made and gives the reviewer a lot\nof context.\n\n## Using tags {#tags}\n\nTags are manually entered labels that can be used to categorize CLs. These may\nbe supported by tools or just used by team convention.\n\nFor example:\n\n-   \"[tag]\"\n-   \"[a longer tag]\"\n-   \"#tag\"\n-   \"tag:\"\n\nUsing tags is optional.\n\nWhen adding tags, consider whether they should be in the [body](#informative) of\nthe CL description or the [first line](#first-line). Limit the usage of tags in\nthe first line, as this can obscure the content.\n\nExamples with and without tags:\n\n``` {.good}\n// Tags are okay in the first line if kept short.\n[banana] Peel the banana before eating.\n\n// Tags can be inlined in content.\nPeel the #banana before eating.\n\n// Tags are optional.\nPeel the banana before eating.\n\n// Multiple tags are acceptable if kept short.\n#banana #apple: Assemble a fruit basket.\n\n// Tags can go anywhere in the CL description.\n> Assemble a fruit basket.\n>\n> #banana #apple\n```\n\n``` {.bad}\n// Too many tags (or tags that are too long) overwhelm the first line.\n//\n// Instead, consider whether the tags can be moved into the description body\n// and/or shortened.\n[banana peeler factory factory][apple picking service] Assemble a fruit basket.\n```\n\n## Generated CL descriptions\n\nSome CLs are generated by tools. Whenever possible, their descriptions should\nalso follow the advice here. That is, their first line should be short, focused,\nand stand alone, and the CL description body should include informative details\nthat help reviewers and future code searchers understand each CL's effect.\n\n## Review the description before submitting the CL\n\nCLs can undergo significant change during review. It can be worthwhile to review\na CL description before submitting the CL, to ensure that the description still\nreflects what the CL does.\n\nNext: [Small CLs](small-cls.md)\n"
  },
  {
    "path": "review/developer/handling-comments.md",
    "content": "# How to handle reviewer comments\n\n\n\nWhen you've sent a CL out for review, it's likely that your reviewer will\nrespond with several comments on your CL. Here are some useful things to know\nabout handling reviewer comments.\n\n## Don't Take it Personally {#personal}\n\nThe goal of review is to maintain the quality of our codebase and our products.\nWhen a reviewer provides a critique of your code, think of it as their attempt\nto help you, the codebase, and Google, rather than as a personal attack on you\nor your abilities.\n\nSometimes reviewers feel frustrated and they express that frustration in their\ncomments. This isn't a good practice for reviewers, but as a developer you\nshould be prepared for this. Ask yourself, \"What is the constructive thing that\nthe reviewer is trying to communicate to me?\" and then operate as though that's\nwhat they actually said.\n\n**Never respond in anger to code review comments.** That is a serious breach of\nprofessional etiquette that will live forever in the code review tool. If you\nare too angry or annoyed to respond kindly, then walk away from your computer\nfor a while, or work on something else until you feel calm enough to reply\npolitely.\n\nIn general, if a reviewer isn't providing feedback in a way that's constructive\nand polite, explain this to them in person. If you can't talk to them in person\nor on a video call, then send them a private email. Explain to them in a kind\nway what you don't like and what you'd like them to do differently. If they also\nrespond in a non-constructive way to this private discussion, or it doesn't have\nthe intended effect, then\nescalate to your manager as\nappropriate.\n\n## Fix the Code {#code}\n\nIf a reviewer says that they don't understand something in your code, your first\nresponse should be to clarify the code itself. If the code can't be clarified,\nadd a code comment that explains why the code is there. If a comment seems\npointless, only then should your response be an explanation in the code review\ntool.\n\nIf a reviewer didn't understand some piece of your code, it's likely other\nfuture readers of the code won't understand either. Writing a response in the\ncode review tool doesn't help future code readers, but clarifying your code or\nadding code comments does help them.\n\n## Think Collaboratively {#think}\n\nWriting a CL can take a lot of work. It's often really satisfying to finally\nsend one out for review, feel like it's done, and be pretty sure that no further\nwork is needed. It can be frustrating to receive comments asking for changes,\nespecially if you don't agree with them.\n\nAt times like this, take a moment to step back and consider if the reviewer is\nproviding valuable feedback that will help the codebase and Google. Your first\nquestion to yourself should always be, \"Do I understand what the reviewer is\nasking for?\"\n\nIf you can't answer that question, ask the reviewer for clarification.\n\nAnd then, if you understand the comments but disagree with them, it's important\nto think collaboratively, not combatively or defensively:\n\n```txt {.bad}\nBad: \"No, I'm not going to do that.\"\n```\n\n```txt {.good}\nGood: \"I went with X because of [these pros/cons] with [these tradeoffs]\nMy understanding is that using Y would be worse because of [these reasons].\nAre you suggesting that Y better serves the original tradeoffs, that we should\nweigh the tradeoffs differently, or something else?\"\n```\n\nRemember,\n**[courtesy and respect](https://chromium.googlesource.com/chromium/src/+/master/docs/cr_respect.md)\nshould always be a first priority**. If you disagree with the reviewer, find\nways to collaborate: ask for clarifications, discuss pros/cons, and provide\nexplanations of why your method of doing things is better for the codebase,\nusers, and/or Google.\n\nSometimes, you might know something about the users, codebase, or CL that the\nreviewer doesn't know. [Fix the code](#code) where appropriate, and engage your\nreviewer in discussion, including giving them more context. Usually you can come\nto some consensus between yourself and the reviewer based on technical facts.\n\n## Resolving Conflicts {#conflicts}\n\nYour first step in resolving conflicts should always be to try to come to\nconsensus with your reviewer. If you can't achieve consensus, see\n[The Standard of Code Review](../reviewer/standard.md), which gives principles\nto follow in such a situation.\n"
  },
  {
    "path": "review/developer/index.md",
    "content": "# The CL author's guide to getting through code review\n\nThe pages in this section contain best practices for developers going through\ncode review. These guidelines should help you get through reviews faster and\nwith higher-quality results. You don't have to read them all, but they are\nintended to apply to every Google developer, and many people have found it\nhelpful to read the whole set.\n\n-   [Writing Good CL Descriptions](cl-descriptions.md)\n-   [Small CLs](small-cls.md)\n-   [How to Handle Reviewer Comments](handling-comments.md)\n\nSee also [How to Do a Code Review](../reviewer/index.md), which gives detailed\nguidance for code reviewers.\n"
  },
  {
    "path": "review/developer/small-cls.md",
    "content": "# Small CLs\n\n\n\n## Why Write Small CLs? {#why}\n\nSmall, simple CLs are:\n\n-   **Reviewed more quickly.** It's easier for a reviewer to find five minutes\n    several times to review small CLs than to set aside a 30 minute block to\n    review one large CL.\n-   **Reviewed more thoroughly.** With large changes, reviewers and authors tend\n    to get frustrated by large volumes of detailed commentary shifting back and\n    forth—sometimes to the point where important points get missed or dropped.\n-   **Less likely to introduce bugs.** Since you're making fewer changes, it's\n    easier for you and your reviewer to reason effectively about the impact of\n    the CL and see if a bug has been introduced.\n-   **Less wasted work if they are rejected.** If you write a huge CL and then\n    your reviewer says that the overall direction is wrong, you've wasted a lot\n    of work.\n-   **Easier to merge.** Working on a large CL takes a long time, so you will\n    have lots of conflicts when you merge, and you will have to merge\n    frequently.\n-   **Easier to design well.** It's a lot easier to polish the design and code\n    health of a small change than it is to refine all the details of a large\n    change.\n-   **Less blocking on reviews.** Sending self-contained portions of your\n    overall change allows you to continue coding while you wait for your current\n    CL in review.\n-   **Simpler to roll back.** A large CL will more likely touch files that get\n    updated between the initial CL submission and a rollback CL, complicating\n    the rollback (the intermediate CLs will probably need to be rolled back\n    too).\n\nNote that **reviewers have discretion to reject your change outright for the\nsole reason of it being too large.** Usually they will thank you for your\ncontribution but request that you somehow make it into a series of smaller\nchanges. It can be a lot of work to split up a change after you've already\nwritten it, or require lots of time arguing about why the reviewer should accept\nyour large change. It's easier to just write small CLs in the first place.\n\n## What is Small? {#what-is-small}\n\n<a id=\"what_is_small\"></a> <!-- Keep previous permalink to avoid breaking old links. -->\n\nIn general, the right size for a CL is **one self-contained change**. This means\nthat:\n\n-   The CL makes a minimal change that addresses **just one thing**. This is\n    usually just one part of a feature, rather than a whole feature at once. In\n    general it's better to err on the side of writing CLs that are too small vs.\n    CLs that are too large. Work with your reviewer to find out what an\n    acceptable size is.\n-   The CL should [include related test code](#test_code).\n-   Everything the reviewer needs to understand about the CL (except future\n    development) is in the CL, the CL's description, the existing codebase, or a\n    CL they've already reviewed.\n-   The system will continue to work well for its users and for the developers\n    after the CL is checked in.\n-   The CL is not so small that its implications are difficult to understand. If\n    you add a new API, you should include a usage of the API in the same CL so\n    that reviewers can better understand how the API will be used. This also\n    prevents checking in unused APIs.\n\nThere are no hard and fast rules about how large is \"too large.\" 100 lines is\nusually a reasonable size for a CL, and 1000 lines is usually too large, but\nit's up to the judgment of your reviewer. The number of files that a change is\nspread across also affects its \"size.\" A 200-line change in one file might be\nokay, but spread across 50 files it would usually be too large.\n\nKeep in mind that although you have been intimately involved with your code from\nthe moment you started to write it, the reviewer often has no context. What\nseems like an acceptably-sized CL to you might be overwhelming to your reviewer.\nWhen in doubt, write CLs that are smaller than you think you need to write.\nReviewers rarely complain about getting CLs that are too small.\n\n## When are Large CLs Okay? {#large-okay}\n\n<a id=\"large_okay\"></a> <!-- Keep previous permalink to avoid breaking old links. -->\n\nThere are a few situations in which large changes aren't as bad:\n\n-   You can usually count deletion of an entire file as being just one line of\n    change, because it doesn't take the reviewer very long to review.\n-   Sometimes a large CL has been generated by an automatic refactoring tool\n    that you trust completely, and the reviewer's job is just to verify and say\n    that they really do want the change. These CLs can be larger, although some\n    of the caveats from above (such as merging and testing) still apply.\n\n## Writing Small CLs Efficiently {#efficiently}\n\nIf you write a small CL and then you wait for your reviewer to approve it before\nyou write your next CL, then you're going to waste a lot of time. So you want to\nfind some way to work that won't block you while you're waiting for review. This\ncould involve having multiple projects to work on simultaneously, finding\nreviewers who agree to be immediately available, doing in-person reviews, pair\nprogramming, or splitting your CLs in a way that allows you to continue working\nimmediately.\n\n## Splitting CLs {#splitting}\n\nWhen starting work that will have multiple CLs with potential dependencies among\neach other, it's often useful to think about how to split and organize those CLs\nat a high level before diving into coding.\n\nBesides making things easier for you as an author to manage and organize your\nCLs, it also makes things easier for your code reviewers, which in turn makes\nyour code reviews more efficient.\n\nHere are some strategies for splitting work into different CLs.\n\n### Stacking Multiple Changes on Top of Each Other {#stacking}\n\nOne way to split up a CL without blocking yourself is to write one small CL,\nsend it off for review, and then immediately start writing another CL *based* on\nthe first CL. Most version control systems allow you to do this somehow.\n\n### Splitting by Files {#splitting-files}\n\nAnother way to split up a CL is by groupings of files that will require\ndifferent reviewers but are otherwise self-contained changes.\n\nFor example: you send off one CL for modifications to a protocol buffer and\nanother CL for changes to the code that uses that proto. You have to submit the\nproto CL before the code CL, but they can both be reviewed simultaneously. If\nyou do this, you might want to inform both sets of reviewers about the other CL\nthat you wrote, so that they have context for your changes.\n\nAnother example: you send one CL for a code change and another for the\nconfiguration or experiment that uses that code; this is easier to roll back\ntoo, if necessary, as configuration/experiment files are sometimes pushed to\nproduction faster than code changes.\n\n### Splitting Horizontally {#splitting-horizontally}\n\nConsider creating shared code or stubs that help isolate changes between layers\nof the tech stack. This not only helps expedite development but also encourages\nabstraction between layers.\n\nFor example: You created a calculator app with client, API, service, and data\nmodel layers. A shared proto signature can abstract the service and data model\nlayers from each other. Similarly, an API stub can split the implementation of\nclient code from service code and enable them to move forward independently.\nSimilar ideas can also be applied to more granular function or class level\nabstractions.\n\n### Splitting Vertically {#splitting-vertically}\n\nOrthogonal to the layered, horizontal approach, you can instead break down your\ncode into smaller, full-stack, vertical features. Each of these features can be\nindependent parallel implementation tracks. This enables some tracks to move\nforward while other tracks are awaiting review or feedback.\n\nBack to our calculator example from\n[Splitting Horizontally](#splitting-horizontally). You now want to support new\noperators, like multiplication and division. You could split this up by\nimplementing multiplication and division as separate verticals or sub-features,\neven though they may have some overlap such as shared button styling or shared\nvalidation logic.\n\n### Splitting Horizontally & Vertically {#splitting-grid}\n\nTo take this a step further, you could combine these approaches and chart out an\nimplementation plan like this, where each cell is its own standalone CL.\nStarting from the model (at the bottom) and working up to the client:\n\n| Layer   | Feature: Multiplication   | Feature: Division               |\n| ------- | ------------------------- | ------------------------------- |\n| Client  | Add button                | Add button                      |\n| API     | Add endpoint              | Add endpoint                    |\n| Service | Implement transformations | Share transformation logic with |\n:         :                           : multiplication                  :\n| Model   | Add proto definition      | Add proto definition            |\n\n## Separate Out Refactorings {#refactoring}\n\nIt's usually best to do refactorings in a separate CL from feature changes or\nbug fixes. For example, moving and renaming a class should be in a different CL\nfrom fixing a bug in that class. It is much easier for reviewers to understand\nthe changes introduced by each CL when they are separate.\n\nSmall cleanups such as fixing a local variable name can be included inside of a\nfeature change or bug fix CL, though. It's up to the judgment of developers and\nreviewers to decide when a refactoring is so large that it will make the review\nmore difficult if included in your current CL.\n\n## Keep related test code in the same CL {#test-code}\n\n<a id=\"test_code\"></a> <!-- Keep previous permalink to avoid breaking old links. -->\n\nCLs should include related test code. Remember that [smallness](#what-is-small)\nhere refers the conceptual idea that the CL should be focused and is not a\nsimplistic function on line count.\n\nTests are expected for all Google changes.\n\nA CL that adds or changes logic should be accompanied by new or updated tests\nfor the new behavior. Pure refactoring CLs (that aren't intended to change\nbehavior) should also be covered by tests; ideally, these tests already exist,\nbut if they don't, you should add them.\n\n*Independent* test modifications can go into separate CLs first, similar to the\n[refactorings guidelines](#refactoring). That includes:\n\n*   Validating pre-existing, submitted code with new tests.\n    *   Ensures that important logic is covered by tests.\n    *   Increases confidence in subsequent refactorings on affected code. For\n        example, if you want to refactor code that isn't already covered by\n        tests, submitting test CLs *before* submitting refactoring CLs can\n        validate that the tested behavior is unchanged before and after the\n        refactoring.\n*   Refactoring the test code (e.g. introduce helper functions).\n*   Introducing larger test framework code (e.g. an integration test).\n\n## Don't Break the Build {#break}\n\nIf you have several CLs that depend on each other, you need to find a way to\nmake sure the whole system keeps working after each CL is submitted. Otherwise\nyou might break the build for all your fellow developers for a few minutes\nbetween your CL submissions (or even longer if something goes wrong unexpectedly\nwith your later CL submissions).\n\n## Can't Make it Small Enough {#cant}\n\nSometimes you will encounter situations where it seems like your CL *has* to be\nlarge. This is very rarely true. Authors who practice writing small CLs can\nalmost always find a way to decompose functionality into a series of small\nchanges.\n\nBefore writing a large CL, consider whether preceding it with a refactoring-only\nCL could pave the way for a cleaner implementation. Talk to your teammates and\nsee if anybody has thoughts on how to implement the functionality in small CLs\ninstead.\n\nIf all of these options fail (which should be extremely rare) then get consent\nfrom your reviewers in advance to review a large CL, so they are warned about\nwhat is coming. In this situation, expect to be going through the review process\nfor a long time, be vigilant about not introducing bugs, and be extra diligent\nabout writing tests.\n\nNext: [How to Handle Reviewer Comments](handling-comments.md)\n"
  },
  {
    "path": "review/emergencies.md",
    "content": "# Emergencies\n\nSometimes there are emergency CLs that must pass through the entire code review\nprocess as quickly as\npossible.\n\n\n\n## What Is An Emergency? {#what}\n\nAn emergency CL would be a **small** change that: allows a major launch to\ncontinue instead of rolling back, fixes a bug significantly affecting users in\nproduction, handles a pressing legal issue, closes a major security hole, etc.\n\nIn emergencies we really do care about the speed of the entire code review\nprocess, not just the [speed of response](reviewer/speed.md). In this case\n*only*, the reviewer should care more about the speed of the review and the\ncorrectness of the code (does it actually resolve the emergency?) than anything\nelse. Also (perhaps obviously) such reviews should take priority over all other\ncode reviews, when they come up.\n\nHowever, after the emergency is resolved you should look over the emergency CLs\nagain and give them a [more thorough review](reviewer/looking-for.md).\n\n## What Is NOT An Emergency? {#not}\n\nTo be clear, the following cases are *not* an emergency:\n\n-   Wanting to launch this week rather than next week (unless there is some\n    actual [hard deadline](#deadlines) for launch such as a partner agreement).\n-   The developer has worked on a feature for a very long time and they really\n    want to get the CL in.\n-   The reviewers are all in another timezone where it is currently nighttime or\n    they are away on an off-site.\n-   It is the end of the day on a Friday and it would just be great to get this\n    CL in before the developer leaves for the weekend.\n-   A manager says that this review has to be complete and the CL checked in\n    today because of a [soft (not hard) deadline](#deadlines).\n-   Rolling back a CL that is causing test failures or build breakages.\n\nAnd so on.\n\n## What Is a Hard Deadline? {#deadlines}\n\nA hard deadline is one where **something disastrous would happen** if you miss\nit. For example:\n\n-   Submitting your CL by a certain date is necessary for a contractual\n    obligation.\n-   Your product will completely fail in the marketplace if not released by a\n    certain date.\n-   Some hardware manufacturers only ship new hardware once a year. If you miss\n    the deadline to submit code to them, that could be disastrous, depending on\n    what type of code you're trying to ship.\n\nDelaying a release for a week is not disastrous. Missing an important conference\nmight be disastrous, but often is not.\n\nMost deadlines are soft deadlines, not hard deadlines. They represent a desire\nfor a feature to be done by a certain time. They are important, but you\nshouldn't be sacrificing code health to make them.\n\nIf you have a long release cycle (several weeks) it can be tempting to sacrifice\ncode review quality to get a feature in before the next cycle. However, this\npattern, if repeated, is a common way for projects to build up overwhelming\ntechnical debt. If developers are routinely submitting CLs near the end of the\ncycle that \"must get in\" with only superficial review, then the team should\nmodify its process so that large feature changes happen early in the cycle and\nhave enough time for good review.\n"
  },
  {
    "path": "review/index.md",
    "content": "\n## Introduction {#intro}\n\nA code review is a process where someone other than the author(s) of a piece of\ncode examines that code.\n\nAt Google, we use code review to maintain the quality of our code and products.\n\nThis documentation is the canonical description of Google's code review\nprocesses and policies.\n\n\n\nThis page is an overview of our code review process. There are two other large\ndocuments that are a part of this guide:\n\n-   **[How To Do A Code Review](reviewer/index.md)**: A detailed guide for code\n    reviewers.\n-   **[The CL Author's Guide](developer/index.md)**: A detailed guide for\n    developers whose CLs are going through review.\n\n## What Do Code Reviewers Look For? {#look_for}\n\nCode reviews should look at:\n\n-   **Design**: Is the code well-designed and appropriate for your system?\n-   **Functionality**: Does the code behave as the author likely intended? Is\n    the way the code behaves good for its users?\n-   **Complexity**: Could the code be made simpler? Would another developer be\n    able to easily understand and use this code when they come across it in the\n    future?\n-   **Tests**: Does the code have correct and well-designed automated tests?\n-   **Naming**: Did the developer choose clear names for variables, classes,\n    methods, etc.?\n-   **Comments**: Are the comments clear and useful?\n-   **Style**: Does the code follow our\n    [style guides](http://google.github.io/styleguide/)?\n-   **Documentation**: Did the developer also update relevant documentation?\n\nSee **[How To Do A Code Review](reviewer/index.md)** for more information.\n\n### Picking the Best Reviewers {#best_reviewers}\n\nIn general, you want to find the *best* reviewers you can who are capable of\nresponding to your review within a reasonable period of time.\n\nThe best reviewer is the person who will be able to give you the most thorough\nand correct review for the piece of code you are writing. This usually means the\nowner(s) of the code, who may or may not be the people in the OWNERS file.\nSometimes this means asking different people to review different parts of the\nCL.\n\nIf you find an ideal reviewer but they are not available, you should at least CC\nthem on your change.\n\n### In-Person Reviews (and Pair Programming) {#in_person}\n\nIf you pair-programmed a piece of code with somebody who was qualified to do a\ngood code review on it, then that code is considered reviewed.\n\nYou can also do in-person code reviews where the reviewer asks questions and the\ndeveloper of the change speaks only when spoken to.\n\n## See Also {#seealso}\n\n-   [How To Do A Code Review](reviewer/index.md): A detailed guide for code\n    reviewers.\n-   [The CL Author's Guide](developer/index.md): A detailed guide for developers\n    whose CLs are going through review.\n"
  },
  {
    "path": "review/reviewer/comments.md",
    "content": "# How to write code review comments\n\n\n\n## Summary\n\n-   Be kind.\n-   Explain your reasoning.\n-   Balance giving explicit directions with just pointing out problems and\n    letting the developer decide.\n-   Encourage developers to simplify code or add code comments instead of just\n    explaining the complexity to you.\n\n## Courtesy\n\nIn general, it is important to be\n[courteous and respectful](https://chromium.googlesource.com/chromium/src/+/master/docs/cr_respect.md)\nwhile also being very clear and helpful to the developer whose code you are\nreviewing. One way to do this is to be sure that you are always making comments\nabout the *code* and never making comments about the *developer*. You don't\nalways have to follow this practice, but you should definitely use it when\nsaying something that might otherwise be upsetting or contentious. For example:\n\nBad: \"Why did **you** use threads here when there's obviously no benefit to be\ngained from concurrency?\"\n\nGood: \"The concurrency model here is adding complexity to the system without any\nactual performance benefit that I can see. Because there's no performance\nbenefit, it's best for this code to be single-threaded instead of using multiple\nthreads.\"\n\n## Explain Why {#why}\n\nOne thing you'll notice about the \"good\" example from above is that it helps the\ndeveloper understand *why* you are making your comment. You don't always need to\ninclude this information in your review comments, but sometimes it's appropriate\nto give a bit more explanation around your intent, the best practice you're\nfollowing, or how your suggestion improves code health.\n\n## Giving Guidance {#guidance}\n\n**In general it is the developer's responsibility to fix a CL, not the\nreviewer's.** You are not required to do detailed design of a solution or write\ncode for the developer.\n\nThis doesn't mean the reviewer should be unhelpful, though. In general you\nshould strike an appropriate balance between pointing out problems and providing\ndirect guidance. Pointing out problems and letting the developer make a decision\noften helps the developer learn, and makes it easier to do code reviews. It also\ncan result in a better solution, because the developer is closer to the code\nthan the reviewer is.\n\nHowever, sometimes direct instructions, suggestions, or even code are more\nhelpful. The primary goal of code review is to get the best CL possible. A\nsecondary goal is improving the skills of developers so that they require less\nand less review over time.\n\nRemember that people learn from reinforcement of what they are doing well and\nnot just what they could do better. If you see things you like in the CL,\ncomment on those too! Examples: developer cleaned up a messy algorithm, added\nexemplary test coverage, or you as the reviewer learned something from the CL.\nJust as with all comments, include [why](#why) you liked something, further\nencouraging the developer to continue good practices.\n\n## Label comment severity {#label-comment-severity}\n\nConsider labeling the severity of your comments, differentiating required\nchanges from guidelines or suggestions.\n\nHere are some examples:\n\n> Nit: This is a minor thing. Technically you should do it, but it won’t hugely\n> impact things.\n>\n> Optional (or Consider): I think this may be a good idea, but it’s not strictly\n> required.\n>\n> FYI: I don’t expect you to do this in this CL, but you may find this\n> interesting to think about for the future.\n\nThis makes review intent explicit and helps authors prioritize the importance of\nvarious comments. It also helps avoid misunderstandings; for example, without\ncomment labels, authors may interpret all comments as mandatory, even if some\ncomments are merely intended to be informational or optional.\n\n## Accepting Explanations {#explanations}\n\nIf you ask a developer to explain a piece of code that you don't understand,\nthat should usually result in them **rewriting the code more clearly**.\nOccasionally, adding a comment in the code is also an appropriate response, as\nlong as it's not just explaining overly complex code.\n\n**Explanations written only in the code review tool are not helpful to future\ncode readers.** They are acceptable only in a few circumstances, such as when\nyou are reviewing an area you are not very familiar with and the developer\nexplains something that normal readers of the code would have already known.\n\nNext: [Handling Pushback in Code Reviews](pushback.md)\n"
  },
  {
    "path": "review/reviewer/index.md",
    "content": "# How to do a code review\n\nThe pages in this section contain recommendations on the best way to do code\nreviews, based on long experience. All together they represent one complete\ndocument, broken up into many separate sections. You don't have to read them\nall, but many people have found it very helpful to themselves and their team to\nread the entire set.\n\n-   [The Standard of Code Review](standard.md)\n-   [What to Look For In a Code Review](looking-for.md)\n-   [Navigating a CL in Review](navigate.md)\n-   [Speed of Code Reviews](speed.md)\n-   [How to Write Code Review Comments](comments.md)\n-   [Handling Pushback in Code Reviews](pushback.md)\n\nSee also the [CL Author's Guide](../developer/index.md), which gives detailed\nguidance to developers whose CLs are undergoing review.\n"
  },
  {
    "path": "review/reviewer/looking-for.md",
    "content": "# What to look for in a code review\n\n\n\nNote: Always make sure to take into account\n[The Standard of Code Review](standard.md) when considering each of these\npoints.\n\n## Design\n\nThe most important thing to cover in a review is the overall design of the CL.\nDo the interactions of various pieces of code in the CL make sense? Does this\nchange belong in your codebase, or in a library? Does it integrate well with the\nrest of your system? Is now a good time to add this functionality?\n\n## Functionality\n\nDoes this CL do what the developer intended? Is what the developer intended good\nfor the users of this code? The \"users\" are usually both end-users (when they\nare affected by the change) and developers (who will have to \"use\" this code in\nthe future).\n\nMostly, we expect developers to test CLs well-enough that they work correctly by\nthe time they get to code review. However, as the reviewer you should still be\nthinking about edge cases, looking for concurrency problems, trying to think\nlike a user, and making sure that there are no bugs that you see just by reading\nthe code.\n\nYou *can* validate the CL if you want—the time when it's most important for a\nreviewer to check a CL's behavior is when it has a user-facing impact, such as a\n**UI change**. It's hard to understand how some changes will impact a user when\nyou're just reading the code. For changes like that, you can have the developer\ngive you a demo of the functionality if it's too inconvenient to patch in the CL\nand try it yourself.\n\nAnother time when it's particularly important to think about functionality\nduring a code review is if there is some sort of **parallel programming** going\non in the CL that could theoretically cause deadlocks or race conditions. These\nsorts of issues are very hard to detect by just running the code and usually\nneed somebody (both the developer and the reviewer) to think through them\ncarefully to be sure that problems aren't being introduced. (Note that this is\nalso a good reason not to use concurrency models where race conditions or\ndeadlocks are possible—it can make it very complex to do code reviews or\nunderstand the code.)\n\n## Complexity\n\nIs the CL more complex than it should be? Check this at every level of the\nCL—are individual lines too complex? Are functions too complex? Are classes too\ncomplex? \"Too complex\" usually means **\"can't be understood quickly by code\nreaders.\"** It can also mean **\"developers are likely to introduce bugs when\nthey try to call or modify this code.\"**\n\nA particular type of complexity is **over-engineering**, where developers have\nmade the code more generic than it needs to be, or added functionality that\nisn't presently needed by the system. Reviewers should be especially vigilant\nabout over-engineering. Encourage developers to solve the problem they know\nneeds to be solved *now*, not the problem that the developer speculates *might*\nneed to be solved in the future. The future problem should be solved once it\narrives and you can see its actual shape and requirements in the physical\nuniverse.\n\n## Tests\n\nAsk for unit, integration, or end-to-end\ntests as appropriate for the change. In general, tests should be added in the\nsame CL as the production code unless the CL is handling an\n[emergency](../emergencies.md).\n\nMake sure that the tests in the CL are correct, sensible, and useful. Tests do\nnot test themselves, and we rarely write tests for our tests—a human must ensure\nthat tests are valid.\n\nWill the tests actually fail when the code is broken? If the code changes\nbeneath them, will they start producing false positives? Does each test make\nsimple and useful assertions? Are the tests separated appropriately between\ndifferent test methods?\n\nRemember that tests are also code that has to be maintained. Don't accept\ncomplexity in tests just because they aren't part of the main binary.\n\n## Naming\n\nDid the developer pick good names for everything? A good name is long enough to\nfully communicate what the item is or does, without being so long that it\nbecomes hard to read.\n\n## Comments\n\nDid the developer write clear comments in understandable English? Are all of the\ncomments actually necessary? Usually comments are useful when they **explain\nwhy** some code exists, and should not be explaining *what* some code is doing.\nIf the code isn't clear enough to explain itself, then the code should be made\nsimpler. There are some exceptions (regular expressions and complex algorithms\noften benefit greatly from comments that explain what they're doing, for\nexample) but mostly comments are for information that the code itself can't\npossibly contain, like the reasoning behind a decision.\n\nIt can also be helpful to look at comments that were there before this CL. Maybe\nthere is a TODO that can be removed now, a comment advising against this change\nbeing made, etc.\n\nNote that comments are different from *documentation* of classes, modules, or\nfunctions, which should instead express the purpose of a piece of code, how it\nshould be used, and how it behaves when used.\n\n## Style\n\nWe have [style guides](http://google.github.io/styleguide/) at Google for all\nof our major languages, and even for most of the minor languages. Make sure the\nCL follows the appropriate style guides.\n\nIf you want to improve some style point that isn't in the style guide, prefix\nyour comment with \"Nit:\" to let the developer know that it's a nitpick that you\nthink would improve the code but isn't mandatory. Don't block CLs from being\nsubmitted based only on personal style preferences.\n\nThe author of the CL should not include major style changes combined with other\nchanges. It makes it hard to see what is being changed in the CL, makes merges\nand rollbacks more complex, and causes other problems. For example, if the\nauthor wants to reformat the whole file, have them send you just the\nreformatting as one CL, and then send another CL with their functional changes\nafter that.\n\n## Consistency\n\nWhat if the existing code is inconsistent with the style guide? Per our\n[code review principles](standard.md#principles), the style guide is the\nabsolute authority: if something is required by the style guide, the CL should\nfollow the guidelines.\n\nIn some cases, the style guide makes recommendations rather than declaring\nrequirements. In these cases, it's a judgment call whether the new code should\nbe consistent with the recommendations or the surrounding code. Bias towards\nfollowing the style guide unless the local inconsistency would be too confusing.\n\nIf no other rule applies, the author should maintain consistency with the\nexisting code.\n\nEither way, encourage the author to file a bug and add a TODO for cleaning up\nexisting code.\n\n## Documentation\n\nIf a CL changes how users build, test, interact with, or release code, check to\nsee that it also updates associated documentation, including\nREADMEs, g3doc pages, and any generated\nreference docs. If the CL deletes or deprecates code, consider whether the\ndocumentation should also be deleted.\nIf documentation is\nmissing, ask for it.\n\n## Every Line {#every-line}\n\nIn the general case, look at *every* line of code that you have been assigned to\nreview. Some things like data files, generated code, or large data structures\nyou can scan over sometimes, but don't scan over a human-written class,\nfunction, or block of code and assume that what's inside of it is okay.\nObviously some code deserves more careful scrutiny than other code&mdash;that's\na judgment call that you have to make&mdash;but you should at least be sure that\nyou *understand* what all the code is doing.\n\nIf it's too hard for you to read the code and this is slowing down the review,\nthen you should let the developer know that\nand wait for them to clarify it before you try to review it. At Google, we hire\ngreat software engineers, and you are one of them. If you can't understand the\ncode, it's very likely that other developers won't either. So you're also\nhelping future developers understand this code, when you ask the developer to\nclarify it.\n\nIf you understand the code but you don't feel qualified to do some part of the\nreview, [make sure there is a reviewer](#every-line-exceptions) on the CL who is\nqualified, particularly for complex issues such as privacy, security,\nconcurrency, accessibility, internationalization, etc.\n\n### Exceptions {#every-line-exceptions}\n\nWhat if it doesn't make sense for you to review every line? For example, you are\none of multiple reviewers on a CL and may be asked:\n\n*   To review only certain files that are part of a larger change.\n*   To review only certain aspects of the CL, such as the high-level design,\n    privacy or security implications, etc.\n\nIn these cases, note in a comment which parts you reviewed. Prefer giving\n[LGTM with comments](speed.md#lgtm-with-comments)\n.\n\nIf you instead wish to grant LGTM after confirming that other reviewers have\nreviewed other parts of the CL, note this explicitly in a comment to set\nexpectations. Aim to [respond quickly](speed.md#responses) once the CL has\nreached the desired state.\n\n## Context\n\nIt is often helpful to look at the CL in a broad context. Usually the code\nreview tool will only show you a few lines of code around the parts that are\nbeing changed. Sometimes you have to look at the whole file to be sure that the\nchange actually makes sense. For example, you might see only four new lines\nbeing added, but when you look at the whole file, you see those four lines are\nin a 50-line method that now really needs to be broken up into smaller methods.\n\nIt's also useful to think about the CL in the context of the system as a whole.\nIs this CL improving the code health of the system or is it making the whole\nsystem more complex, less tested, etc.? **Don't accept CLs that degrade the code\nhealth of the system.** Most systems become complex through many small changes\nthat add up, so it's important to prevent even small complexities in new\nchanges.\n\n## Good Things {#good-things}\n\nIf you see something nice in the CL, tell the developer, especially when they\naddressed one of your comments in a great way. Code reviews often just focus on\nmistakes, but they should offer encouragement and appreciation for good\npractices, as well. It’s sometimes even more valuable, in terms of mentoring, to\ntell a developer what they did right than to tell them what they did wrong.\n\n## Summary\n\nIn doing a code review, you should make sure that:\n\n-   The code is well-designed.\n-   The functionality is good for the users of the code.\n-   Any UI changes are sensible and look good.\n-   Any parallel programming is done safely.\n-   The code isn't more complex than it needs to be.\n-   The developer isn't implementing things they *might* need in the future but\n    don't know they need now.\n-   Code has appropriate unit tests.\n-   Tests are well-designed.\n-   The developer used clear names for everything.\n-   Comments are clear and useful, and mostly explain *why* instead of *what*.\n-   Code is appropriately documented (generally in g3doc).\n-   The code conforms to our style guides.\n\nMake sure to review **every line** of code you've been asked to review, look at\nthe **context**, make sure you're **improving code health**, and compliment\ndevelopers on **good things** that they do.\n\nNext: [Navigating a CL in Review](navigate.md)\n"
  },
  {
    "path": "review/reviewer/navigate.md",
    "content": "# Navigating a CL in review\n\n\n\n## Summary\n\nNow that you know [what to look for](looking-for.md), what's the most efficient\nway to manage a review that's spread across multiple files?\n\n1.  Does the change make sense? Does it have a good\n    [description](../developer/cl-descriptions.md)?\n2.  Look at the most important part of the change first. Is it well-designed\n    overall?\n3.  Look at the rest of the CL in an appropriate sequence.\n\n## Step One: Take a broad view of the change {#step_one}\n\nLook at the [CL description](../developer/cl-descriptions.md) and what the CL\ndoes in general. Does this change even make sense? If this change shouldn't have\nhappened in the first place, please respond immediately with an explanation of\nwhy the change should not be happening. When you reject a change like this, it's\nalso a good idea to suggest to the developer what they should have done instead.\n\nFor example, you might say \"Looks like you put some good work into this, thanks!\nHowever, we're actually going in the direction of removing the FooWidget system\nthat you're modifying here, and so we don't want to make any new modifications\nto it right now. How about instead you refactor our new BarWidget class?\"\n\nNote that not only did the reviewer reject the current CL and provide an\nalternative suggestion, but they did it *courteously*. This kind of courtesy is\nimportant because we want to show that we respect each other as developers even\nwhen we disagree.\n\nIf you get more than a few CLs that represent changes you don't want to make,\nyou should consider re-working your team's development process or the posted\nprocess for external contributors so that there is more communication before CLs\nare written. It's better to tell people \"no\" before they've done a ton of work\nthat now has to be thrown away or drastically re-written.\n\n## Step Two: Examine the main parts of the CL {#step_two}\n\nFind the file or files that are the \"main\" part of this CL. Often, there is one\nfile that has the largest number of logical changes, and it's the major piece of\nthe CL. Look at these major parts first. This helps give context to all of the\nsmaller parts of the CL, and generally accelerates doing the code review. If the\nCL is too large for you to figure out which parts are the major parts, ask the\ndeveloper what you should look at first, or ask them to\n[split up the CL into multiple CLs](../developer/small-cls.md).\n\nIf you see some major design problems with this part of the CL, you should send\nthose comments immediately, even if you don't have time to review the rest of\nthe CL right now. In fact, reviewing the rest of the CL might be a waste of\ntime, because if the design problems are significant enough, a lot of the other\ncode under review is going to disappear and not matter anyway.\n\nThere are two major reasons it's so important to send these major design\ncomments out immediately:\n\n-   Developers often mail a CL and then immediately start new work based on that\n    CL while they wait for review. If there are major design problems in the CL\n    you're reviewing, they're also going to have to re-work their later CL. You\n    want to catch them before they've done too much extra work on top of the\n    problematic design.\n-   Major design changes take longer to do than small changes. Developers nearly\n    all have deadlines; in order to make those deadlines and still have quality\n    code in the codebase, the developer needs to start on any major re-work of\n    the CL as soon as possible.\n\n## Step Three: Look through the rest of the CL in an appropriate sequence {#step_three}\n\nOnce you've confirmed there are no major design problems with the CL as a whole,\ntry to figure out a logical sequence to look through the files while also making\nsure you don't miss reviewing any file. Usually after you've looked through the\nmajor files, it's simplest to just go through each file in the order that\nthe code review tool presents them to you. Sometimes it's also helpful to read the tests\nfirst before you read the main code, because then you have an idea of what the\nchange is supposed to be doing.\n\nNext: [Speed of Code Reviews](speed.md)\n"
  },
  {
    "path": "review/reviewer/pushback.md",
    "content": "# Handling pushback in code reviews\n\n\n\nSometimes a developer will push back on a code review. Either they will disagree\nwith your suggestion or they will complain that you are being too strict in\ngeneral.\n\n## Who is right? {#who_is_right}\n\nWhen a developer disagrees with your suggestion, first take a moment to consider\nif they are correct. Often, they are closer to the code than you are, and so\nthey might really have a better insight about certain aspects of it. Does their\nargument make sense? Does it make sense from a code health perspective? If so,\nlet them know that they are right and let the issue drop.\n\nHowever, developers are not always right. In this case the reviewer should\nfurther explain why they believe that their suggestion is correct. A good\nexplanation demonstrates both an understanding of the developer's reply, and\nadditional information about why the change is being requested.\n\nIn particular, when the reviewer believes their suggestion will improve code\nhealth, they should continue to advocate for the change, if they believe the\nresulting code quality improvement justifies the additional work requested.\n**Improving code health tends to happen in small steps.**\n\nSometimes it takes a few rounds of explaining a suggestion before it really\nsinks in. Just make sure to always stay [polite](comments.md#courtesy) and let\nthe developer know that you *hear* what they're saying, you just don't *agree*.\n\n## Upsetting Developers {#upsetting_developers}\n\nReviewers sometimes believe that the developer will be upset if the reviewer\ninsists on an improvement. Sometimes developers do become upset, but it is\nusually brief and they become very thankful later that you helped them improve\nthe quality of their code. Usually, if you are [polite](comments.md#courtesy) in\nyour comments, developers actually don't become upset at all, and the worry is\njust in the reviewer's mind. Upsets are usually more about\n[the way comments are written](comments.md#courtesy) than about the reviewer's\ninsistence on code quality.\n\n## Cleaning It Up Later {#later}\n\nA common source of push back is that developers (understandably) want to get\nthings done. They don't want to go through another round of review just to get\nthis CL in. So they say they will clean something up in a later CL, and thus you\nshould LGTM *this* CL now. Some developers are very good about this, and will\nimmediately write a follow-up CL that fixes the issue. However, experience shows\nthat as more time passes after a developer writes the original CL, the less\nlikely this clean up is to happen. In fact, usually unless the developer does\nthe clean up *immediately* after the present CL, it never happens. This isn't\nbecause developers are irresponsible, but because they have a lot of work to do\nand the cleanup gets lost or forgotten in the press of other work. Thus, it is\nusually best to insist that the developer clean up their CL *now*, before the\ncode is in the codebase and \"done.\" Letting people \"clean things up later\" is a\ncommon way for codebases to degenerate.\n\nIf a CL introduces new complexity, it must be cleaned up before submission\nunless it is an [emergency](../emergencies.md). If the CL exposes surrounding\nproblems and they can't be addressed right now, the developer should file a bug\nfor the cleanup and assign it to themselves so that it doesn't get lost. They\ncan optionally also write a TODO comment in the code that references the filed\nbug.\n\n## General Complaints About Strictness {#strictness}\n\nIf you previously had fairly lax code reviews and you switch to having strict\nreviews, some developers will complain very loudly. Improving the\n[speed](speed.md) of your code reviews usually causes these complaints to fade\naway.\n\nSometimes it can take months for these complaints to fade away, but eventually\ndevelopers tend to see the value of strict code reviews as they see what great\ncode they help generate. Sometimes the loudest protesters even become your\nstrongest supporters once something happens that causes them to really see the\nvalue you're adding by being strict.\n\n## Resolving Conflicts {#conflicts}\n\nIf you are following all of the above but you still encounter a conflict between\nyourself and a developer that can't be resolved, see\n[The Standard of Code Review](standard.md) for guidelines and principles that\ncan help resolve the conflict.\n"
  },
  {
    "path": "review/reviewer/speed.md",
    "content": "# Speed of Code Reviews\n\n\n\n## Why Should Code Reviews Be Fast? {#why}\n\n**At Google, we optimize for the speed at which a team of developers can produce\na product together**, as opposed to optimizing for the speed at which an\nindividual developer can write code. The speed of individual development is\nimportant, it's just not *as* important as the velocity of the entire team.\n\nWhen code reviews are slow, several things happen:\n\n*   **The velocity of the team as a whole is decreased.** Yes, the individual\n    who doesn't respond quickly to the review gets other work done. However, new\n    features and bug fixes for the rest of the team are delayed by days, weeks,\n    or months as each CL waits for review and re-review.\n*   **Developers start to protest the code review process.** If a reviewer only\n    responds every few days, but requests major changes to the CL each time,\n    that can be frustrating and difficult for developers. Often, this is\n    expressed as complaints about how \"strict\" the reviewer is being. If the\n    reviewer requests the *same* substantial changes (changes which really do\n    improve code health), but responds *quickly* every time the developer makes\n    an update, the complaints tend to disappear. **Most complaints about the\n    code review process are actually resolved by making the process faster.**\n*   **Code health can be impacted.** When reviews are slow, there is increased\n    pressure to allow developers to submit CLs that are not as good as they\n    could be. Slow reviews also discourage code cleanups, refactorings, and\n    further improvements to existing CLs.\n\n## How Fast Should Code Reviews Be? {#fast}\n\nIf you are not in the middle of a focused task, **you should do a code review\nshortly after it comes in.**\n\n**One business day is the maximum time it should take to respond** to a code\nreview request (i.e., first thing the next morning).\n\nFollowing these guidelines means that a typical CL should get multiple rounds of\nreview (if needed) within a single day.\n\n## Speed vs. Interruption {#interruption}\n\nThere is one time where the consideration of personal velocity trumps team\nvelocity. **If you are in the middle of a focused task, such as writing code,\ndon't interrupt yourself to do a code review.**\nResearch has shown that it can\ntake a long time for a developer to get back into a smooth flow of development\nafter being interrupted. So interrupting yourself while coding is actually\n*more* expensive to the team than making another developer wait a bit for a code\nreview.\n\nInstead, wait for a break point in your work before you respond to a request for\nreview. This could be when your current coding task is completed, after lunch,\nreturning from a meeting, coming back from the breakroom, etc.\n\n## Fast Responses {#responses}\n\nWhen we talk about the speed of code reviews, it is the *response* time that we\nare concerned with, as opposed to how long it takes a CL to get through the\nwhole review and be submitted. The whole process should also be fast, ideally,\nbut **it's even more important for the *individual responses* to come quickly\nthan it is for the whole process to happen rapidly.**\n\nEven if it sometimes takes a long time to get through the entire review\n*process*, having quick responses from the reviewer throughout the process\nsignificantly eases the frustration developers can feel with \"slow\" code\nreviews.\n\nIf you are too busy to do a full review on a CL when it comes in, you can still\nsend a quick response that lets the developer know when you will get to it,\nsuggest other reviewers who might be able to respond more quickly, or\n[provide some initial broad comments](navigate.md). (Note: none of this means\nyou should interrupt coding even to send a response like this&mdash;send the\nresponse at a reasonable break point in your work.)\n\n**It is important that reviewers spend enough time on review that they are\ncertain their \"LGTM\" means \"this code meets [our standards](standard.md).\"**\nHowever, individual responses should still ideally be [fast](#fast).\n\n## Cross-Time-Zone Reviews {#tz}\n\nWhen dealing with time zone differences, try to get back to the author while\nthey have time to respond before the end of their working hours. If they have\nalready finished work for the day, then try to make sure your review is done\nbefore they start work the next day.\n\n## LGTM With Comments {#lgtm-with-comments}\n\nIn order to speed up code reviews, there are certain situations in which a\nreviewer should give LGTM/Approval even though they are also leaving unresolved\ncomments on the CL. This should be done when at least one of the following\napplies:\n\n*   The reviewer is confident that the developer will appropriately address all\n    the reviewer's remaining comments.\n*   The comments don't *have* to be addressed by the developer.\n*   The suggestions are minor, e.g. sort imports, fix a nearby typo, apply a\n    suggested fix, remove an unused dep, etc.\n\nThe reviewer should specify which of these options they intend, if it is not\notherwise clear.\n\nLGTM With Comments is especially worth considering when the developer and\nreviewer are in different time zones and otherwise the developer would be\nwaiting for a whole day just to get \"LGTM, Approval\".\n\n## Large CLs {#large}\n\nIf somebody sends you a code review that is so large you're not sure when you\nwill be able to have time to review it, your typical response should be to ask\nthe developer to\n[split the CL into several smaller CLs](../developer/small-cls.md) that build on\neach other, instead of one huge CL that has to be reviewed all at once. This is\nusually possible and very helpful to reviewers, even if it takes additional work\nfrom the developer.\n\nIf a CL *can't* be broken up into smaller CLs, and you don't have time to review\nthe entire thing quickly, then at least write some comments on the overall\ndesign of the CL and send it back to the developer for improvement. One of your\ngoals as a reviewer should be to always unblock the developer or enable them to\ntake some sort of further action quickly, without sacrificing code health to do\nso.\n\n## Code Review Improvements Over Time {#time}\n\nIf you follow these guidelines and you are strict with your code reviews, you\nshould find that the entire code review process tends to go faster and faster\nover time. Developers learn what is required for healthy code, and send you CLs\nthat are great from the start, requiring less and less review time. Reviewers\nlearn to respond quickly and not add unnecessary latency into the review\nprocess.\nBut **don't compromise on\nthe [code review standards](standard.md) or quality for an imagined improvement\nin velocity**&mdash;it's not actually going to make anything happen more\nquickly, in the long run.\n\n## Emergencies\n\nThere are also [emergencies](../emergencies.md) where CLs must pass through the\n*whole* review process very quickly, and where the quality guidelines would be\nrelaxed. However, please see [What Is An Emergency?](../emergencies.md#what) for\na description of which situations actually qualify as emergencies and which\ndon't.\n\nNext: [How to Write Code Review Comments](comments.md)\n"
  },
  {
    "path": "review/reviewer/standard.md",
    "content": "# The Standard of Code Review\n\n\n\nThe primary purpose of code review is to make sure that the overall\ncode health of Google's code\nbase is improving over time. All of the tools and processes of code review are\ndesigned to this end.\n\nIn order to accomplish this, a series of trade-offs have to be balanced.\n\nFirst, developers must be able to _make progress_ on their tasks. If you never\nsubmit an improvement to the codebase, then the codebase never improves. Also,\nif a reviewer makes it very difficult for _any_ change to go in, then developers\nare disincentivized to make improvements in the future.\n\nOn the other hand, it is the duty of the reviewer to make sure that each CL is\nof such a quality that the overall code health of their codebase is not\ndecreasing as time goes on. This can be tricky, because often, codebases degrade\nthrough small decreases in code health over time, especially when a team is\nunder significant time constraints and they feel that they have to take\nshortcuts in order to accomplish their goals.\n\nAlso, a reviewer has ownership and responsibility over the code they are\nreviewing. They want to ensure that the codebase stays consistent, maintainable,\nand all of the other things mentioned in\n[\"What to look for in a code review.\"](looking-for.md)\n\nThus, we get the following rule as the standard we expect in code reviews:\n\n**In general, reviewers should favor approving a CL once it is in a state where\nit definitely improves the overall\ncode health of the system\nbeing worked on, even if the CL isn't perfect.**\n\nThat is _the_ senior principle among all of the code review guidelines.\n\nThere are limitations to this, of course. For example, if a CL adds a feature\nthat the reviewer doesn't want in their system, then the reviewer can certainly\ndeny approval even if the code is well-designed.\n\nA key point here is that there is no such thing as \"perfect\" code&mdash;there is\nonly _better_ code. Reviewers should not require the author to polish every tiny\npiece of a CL before granting approval. Rather, the reviewer should balance out\nthe need to make forward progress compared to the importance of the changes they\nare suggesting. Instead of seeking perfection, what a reviewer should seek is\n_continuous improvement_. A CL that, as a whole, improves the maintainability,\nreadability, and understandability of the system shouldn't be delayed for days\nor weeks because it isn't \"perfect.\"\n\nReviewers should _always_ feel free to leave comments expressing that something\ncould be better, but if it's not very important, prefix it with something like\n\"Nit: \" to let the author know that it's just a point of polish that they could\nchoose to ignore.\n\nNote: Nothing in this document justifies checking in CLs that definitely\n_worsen_ the overall code health of the system. The only time you would do that\nwould be in an [emergency](../emergencies.md).\n\n## Mentoring\n\nCode review can have an important function of teaching developers something new\nabout a language, a framework, or general software design principles. It's\nalways fine to leave comments that help a developer learn something new. Sharing\nknowledge is part of improving the code health of a system over time. Just keep\nin mind that if your comment is purely educational, but not critical to meeting\nthe standards described in this document, prefix it with \"Nit: \" or otherwise\nindicate that it's not mandatory for the author to resolve it in this CL.\n\n## Principles {#principles}\n\n*   Technical facts and data overrule opinions and personal preferences.\n\n*   On matters of style, the [style guide](http://google.github.io/styleguide/)\n    is the absolute authority. Any purely style point (whitespace, etc.) that is\n    not in the style guide is a matter of personal preference. The style should\n    be consistent with what is there. If there is no previous style, accept the\n    author's.\n\n*   **Aspects of software design are almost never a pure style issue or just a\n    personal preference.** They are based on underlying principles and should be\n    weighed on those principles, not simply by personal opinion. Sometimes there\n    are a few valid options. If the author can demonstrate (either through data\n    or based on solid engineering principles) that several approaches are\n    equally valid, then the reviewer should accept the preference of the author.\n    Otherwise the choice is dictated by standard principles of software design.\n\n*   If no other rule applies, then the reviewer may ask the author to be\n    consistent with what is in the current codebase, as long as that doesn't\n    worsen the overall code health of the system.\n\n## Resolving Conflicts {#conflicts}\n\nIn any conflict on a code review, the first step should always be for the\ndeveloper and reviewer to try to come to consensus, based on the contents of\nthis document and the other documents in\n[The CL Author's Guide](../developer/index.md) and this\n[Reviewer Guide](index.md).\n\nWhen coming to consensus becomes especially difficult, it can help to have a\nface-to-face meeting or a video conference between the reviewer and the author, instead of\njust trying to resolve the conflict through code review comments. (If you do\nthis, though, make sure to record the results of the discussion as a comment on\nthe CL, for future readers.)\n\nIf that doesn't resolve the situation, the most common way to resolve it would\nbe to escalate. Often the\nescalation path is to a broader team discussion, having a Technical Lead weigh in, asking\nfor a decision from a maintainer of the code, or asking an Eng Manager to help\nout. **Don't let a CL sit around because the author and the reviewer can't come\nto an agreement.**\n\nNext: [What to look for in a code review](looking-for.md)\n"
  }
]