Google ’s engineering practice document, do n’t you read it?
Posted May 28, 2020 • 5 min read
Today I share with you an engineering practice document from the Google team:
Google's Engineering Practices documentation.
This document is a long-standing internal project best practice of the Google team. Its purpose is to help developers better conduct code review work, and improve and optimize the code quality of current projects through Code Review, so that developers can maintain and maintain old projects.
In China, the code review has not been ignored, and it is usually only when there are problems to repair. However, building a robust large-scale software application requires code review.
If your team starts the code review, but there is no correct way, this document is for you.
I excerpted some fragments.
First, it contains two parts
- Code reviewer guide
- Code Developer's Guide
Code reviewer guide
This section is the best way to write Code Review based on past experience. It is divided into many independent parts, which together form a complete document. Although you do n’t have to read the documentation, reading it through will be helpful to yourself and the team.
- Code Review standard \ [1 ]
- Key points of Code Review \ [2 ]
- View the steps of CL \ [3 ]
- Code Review speed \ [4 ]
- How to write Code Review reviews \ [5 ]
- Deal with conflicts in Code Review \ [6 ]
Also see the Code Developer ’s Guide \ [7 ], which provides detailed guidance for developers who are working on Code Review.
What aspects should code reviewers focus on?
Code review should focus on the following aspects:
- Design:Is the code carefully designed and suitable for your system?
- Function:Does the code behave the same as the author ’s intention? Can the code respond to user behavior?
- Complexity:Can the code be simpler? Will other developers easily understand and use this code in the future?
- Test:Does the code have correct and well-designed automated tests?
- Naming:Did the developer choose a clear name for variables, classes, methods, etc.?
- Comment:Is the comment clear and useful?
- Style:Does the code follow the style guide \ [8 ]?
- Documents:Have developers updated relevant documents at the same time?
Code Developer Guide
The content of this section of the page is the best practice for developers to conduct code reviews. These guidelines can help you complete audits faster and obtain higher quality results. You do n’t have to read them all, but they are for every Google developer, and it ’s often helpful to read the full text.
- Write CL description \ [9 ]
- Small CL \ [10 ]
- How to deal with reviewer's comments \ [11 ]
Also see the code reviewer's guide \ [12 ], which provides detailed guidance for code reviewers.
Write CL description
The CL description is a public record of what changes and why changed. CL will serve as a permanent record in the version control system and may be read by hundreds of people other than reviewers for a long period of time.
Developers will search for your CL based on the description in the future. Someone may find your changes based on a weak impression of relevance, but without more specific details. If all the important information is in the code rather than the description, it will make it more difficult for them to find your CL.
- A short summary of what is being done.
- For complete sentences, use imperative sentences.
- An empty line follows.
The first line described by CL should be a short summary of what CL is what to do **, followed by a blank line. This is what most code searchers will see most often when browsing the version control history of the code in the future, so the first line should provide enough information so that they can get the actual CL without reading the entire description of the CL. The above is information on what was done.
According to tradition, the first line of the CL description should be a complete sentence, just like a command(a command sentence). For example, "Delete the FizzBuzz RPC and replace it with the new system." Instead of "Deleting the FizzBuzz RPC and replacing it with the new system." However, You don't have to write the rest of the description as imperative.
Body is informative
The rest of the description should be informative. May include a brief description of the problem being solved and why this is the best approach. If the method has any disadvantages, they should be mentioned. If relevant, please include background information such as error numbers, benchmark results, and links to design documents.
Even a small CL needs attention to details. Provide context in the CL description for reference.
Bad CL description
"Fix bug" is an insufficient CL description. What bug? What fix did you make? Other similar bad descriptions include:
- Fix build.
- Add patch.
- Moving code from A to B.
- Phase 1.
- Add convenience functions.
- kill weird URLs.
Some of them are true CL descriptions. Their authors may think that they provided useful information, but did not achieve the purpose of CL description.
Students who are not good in English do n’t need to worry, domestic developers have already translated this guide into Chinese.
The following is the full link of the project, interested friends can take a look.
- Chinese version: https://jimmysong.io/eng-prac...
- English version: https://google.github.io/eng-...
- GitHub address: https://github.com/google/eng...
The above is the sharing of Pharaoh today, I hope you like it.
\ [1 ]Code Review standard:_ https://jimmysong.io/eng-prac ... _
\ [2 ]Code Review Key points:_ https://jimmysong.io/eng-prac ... _
\ [3 ]View CL steps:_ https://jimmysong.io/eng-prac ... _
\ [4 ]Code Review Speed:_ https://jimmysong.io/eng-prac ... _
\ [5 ]How to write Code Review reviews:_ https://jimmysong.io/eng-prac ... _
\ [6 ]Handle conflicts in Code Review:_ https://jimmysong.io/eng-prac ... _
\ [7 ]Code Developer ’s Guide:_ https://jimmysong.io/eng-prac ... _
\ [8 ]Style guide:_ https://google.github.io/styl ... _
\ [9 ]Write a CL description:_ https://jimmysong.io/eng \ -practices/docs/review/developer/cl-descriptions_
\ [10 ]Small CL:_ https://jimmysong.io/eng-prac ... _
\ [11 ]How to handle reviewers ’comments:_ [ https://jimmysong.io/eng-prac ...]( https://jimmysong.io/eng-practices/docs/review/developer/handling- comments) _
\ [12 ]Guide to code reviewers:_ https://jimmysong.io/eng-prac ... _