This article is Almost Human (micro-channel public number: almosthuman2014) reprinted with permission, is prohibited reprint secondary items of: Max Kanat-Alexander Almost Human compilation
Google has previously established a set of general engineering practice guidelines, which covers almost all programming languages and various types of projects. Today, Google open sourced this set of code review ( Code Review ) specifications, which represents a collection of Google’s best practical experience.
Project address: https://github.com/google/eng-practices
Open source project authors or other developers can obtain useful knowledge from this project, so Google has open sourced this code specification and will continue to maintain it. As stated in the project, the current code review specification mainly includes two independent documents:
1. Guidelines for code reviewers
Code review standards
What does the code review hope to achieve
Navigate the list of changes in the code review
Code review speed
How to write a review review
Handling code review rollbacks
2.CL Author's Guide
Write a good modification list description
Build a small list of changes
How to handle comments from code reviewers
The code reviewer's guide includes some of the best ways to do code reviews, all of which are based on long-term experience. The code reviewer's guide was originally a complete document, but the author divided it into 6 parts, which readers can read as needed. The Change List/CL Maker's Guide includes some of the best ways to browse code reviews, so developers can quickly process the review results.
What are code reviews doing
The main purpose of code review is to ensure that the code base is always maintained in a "healthy" state. All tools and processes of code review are built for this purpose. The code review will systematically check the source code, and hope to check out some errors that were not noticed at the beginning of development, so as to improve the code quality.
So what are the code reviews thanking for? Generally speaking, code review hopes to complete the following assessments:
Design: Is the code carefully designed and suitable for our system?
Functionality: Is the behavior of the code consistent with the author's intention? Is the behavior of the code normal to the user?
Complexity: Can the code be simpler? In the future, can other developers understand and use these codes more easily?
Test: Is the code correct, and has it passed a well-designed automated test?
Naming: Did developers choose easy-to-understand names for variables, classes, and methods?
Comment: Are the code comments clear enough and useful?
Style: Does the code adopt a standard writing style?
Documentation: Has the developer updated the relevant documentation?
Since code review requires numerous checks, it is very important to find an excellent reviewer. Generally, different reviewers will conduct detailed review for different parts of the revision list. In addition, you can get Alibaba's latest Java development manual by following the official account Java technology stack reply manual, which is very valuable and meaningful.
Of course, if it is pair programming and your teammates can conduct high-quality code reviews, then the code written in this way can generally be considered as having been reviewed. In addition, we can also conduct face-to-face reviews, and the reviewers will ask the developers some questions.
General specification for code review
The entire code review guide is divided into many modules, and we cannot introduce them all. Therefore, at the end of this article, we will introduce the most general review criteria for Google developers when doing code reviews.
Google stated that they use the following rules as expected standards:
"Generally speaking, once the list of changes can improve the health of the overall code, even if the list of changes is not complete, reviewers should also be inclined to approve the list."
This rule is the highest principle of all code review guidelines. It also has some restrictions. For example, if CL adds some features that the reviewer does not need, then even if the code has been carefully designed, the reviewer should not pass it.
A key point here is that there is no concept of "perfect" code, only better code. Reviewers should not require code authors to polish each small piece of CL before approval.
Rather, the reviewer should weigh the importance of the need for further development and suggestions for modification. What reviewers demand is continuous improvement, not perfect code. CL as a whole, if it can improve the maintainability, readability, and comprehensibility of the system, then don't postpone the update for days or weeks just because it is not perfect.
Reviewers should often leave comments to express practices that lead to better performance. If these practices are not very important, then the prefix "Nit:" needs to be added to let the code author know that these contents can be ignored. " Two-year Code Review practical experience sharing! "Look at this recommendation.
Evaluation guidance
Code review has a very important function, that is, to teach developers some development experience, whether it is language, framework or general software design guidelines. Leaving some comments will always help developers learn some new knowledge, and sharing knowledge is also an important part of improving the health of the system code. Of course, if the reviewer's comments are only educational and are not so important to the standard requirements, then the prefix "Nit:" should be added.
Evaluation criteria
Technical facts and data take precedence over opinions and personal style.
In terms of code style, Google's code style guide is the most authoritative reference material. Any coding habits that are not in the style guide are personal styles, but we should ensure that the basic style is consistent with the Google style guide.
Google Style Guide: http://google.github.io/styleguide/
There are almost no pure style issues or purely personal habits in software design. Many style issues are based on some basic criteria, they are not simply determined by personal opinions. In addition, if the author of the code proves that several methods are equally effective through data or basic engineering principles, the reviewer should accept the author’s style. Otherwise, the choice of preference still depends on the standard principles of software design.
If there are no other applicable rules, then reviewers can require the author’s preferences to be consistent with the current code base without affecting the overall code health.
Conflict resolution
In the code review, if any conflict occurs, the first step should be for the developer and reviewer to reach a consensus based on the CL guidelines for this project. When it is very difficult to reach a consensus, developers and reviewers should communicate face-to-face, not just through the comments under review. If the meeting and discussion cannot be resolved, then the meeting will be expanded. We can reach a final consensus through communication with code maintainers, engineering managers and other developers.
The above is just a general standard of code specification, it is still very abstract, if readers want to know more details, then you can continue to check the project.
Recommend to read more on my blog:
1. A series of tutorials on Java JVM, collections, multithreading, and new features
2. Spring MVC, Spring Boot, Spring Cloud series of tutorials
3. Maven, Git, Eclipse, Intellij IDEA series tool tutorial
Feel good, don’t forget to like + forward!
Finally, pay attention to the WeChat official account of the stack leader: Java technology stack, reply: Welfare, you can get a free copy of the latest Java interview questions I have compiled for 2020. It is really complete (including answers), without any routine. 