This lesson is “How to do a Good Code Review”. The content includes: Why to do a good Code Review, how to do a good Code Review, examples: Code Review of Python Code, how to be a good Reviewer, and the company’s measures for Code Review.

Why do Code Review need to be done

Code Review is the best way to improve Code quality

Enhancing Code Review is your first choice for improving Code quality.

The earlier we find and locate problems in code development, the less it will cost us to fix them.

More than 50% of the bugs were found during Code Review. Code Review will be done in the early stage, and unnecessary rework such as repeated modifications will be reduced in the later stage.

 

Code Review can transfer knowledge across the team

From the perspective of knowledge transfer, Code Review is extremely important.

A good Code Review can help the team transfer knowledge, communicate and learn from each other, improve learning ability, Code writing ability, Code quality, work efficiency and reduce project risks.

In addition, based on Codebase, we can understand the overall project and cultivate systematic thinking mode.

 

Code Review is the best way to learn how to write Code

We should realize that by doing Code Review, we can learn from others’ experience and pass on our experience to others.

If we want to coach someone, the best way is to ask them to write a piece of Code first, and we Review their Code. In the process of coaching others, we can quickly identify problems and help improve.

 

Do Code Review

Can increase the company’s appeal to the top developers

It is very important for the company or team to have Code Review in their work. Not only does it improve people within the company or team, but it also attracts great developers to join the development team.

Companies or teams that have not done Code Review have the following characteristics:

Poor code quality.

② The backup of team members is poor.

③ They can not get effective guidance and improve slowly.

 

Why improve code quality?

① Improving code quality can improve code readability.

② Improving code quality can improve code reusability and reference.

③ Improving code quality can reduce the risk of bugs.

④ Improving code quality can reduce the risk of late patches.

⑤ Improving code quality can reduce the risk of losing control of code.

⑥ Improving code quality can reduce the trouble of project refactoring and upgrading.

Why improve your coding skills

(1) If the ability to code stagnates, it will lead to a career crisis for the individual.

(2) If the code capability stagnates, it means that the team is not growing.

Code Review is a very important way to improve Code quality and capabilities. Both from the perspective of personal development and team development, we need to attach importance to Code Review.

 

How to do a good Code Review

 

Problems that may be found in Code Review

→ spelling mistakes;

→ Unoptimized code;

Unnecessary complex code;

→ already implemented code, and repeated implementation;

→ incomplete notes;

→ Case does not cover all and so on.

 

Have a good attitude in Code Review

Do the following

(1) To all the checked code logic to do “fully understand”, for the review of the code, the familiarity to do “as many as possible”. If the logic of the Code and the reasons behind it are still vague after the Code is reviewed, it is a failed Code Review.

(2) The standard of good code is not only “can run through”, but also needs comprehensive consideration in correctness, readability, reusability, operability and other aspects.

(3) Establish the awareness that Code Review is as important as writing Code. That is:

Code Review, like writing Code, produces higher quality Code.

In many cases, reviewing code is harder than writing code, requiring understanding and finding problems.

(4) To improve the quality of the code as the ultimate goal.

(5) Devote enough time and energy.

Review code often takes as much time as writing code, and sometimes more. Be time conscious.

② Have a sense of responsibility. If a bug occurs, it’s not just the writer’s responsibility, it’s not just QA’s responsibility, it’s the reviewer’s responsibility as well.

 

Features of first-class Code prior to Code Review

 

First-class code has the following characteristics: ① high efficiency; (2) Robustness; (3) concise; (4) short; ⑤ Shareable; ⑥ Testable; ⑦ Portable; ⑧ can be monitored; ⑨ Operation and maintenance; ⑩ Extensible. The above ten standards are summarized and simplified, which can be summarized as follows:

(1) Code correctness and performance;

(2) readable and maintainable code;

③ the operable and runnable code;

(4) shareable and reusable code;

In Code Review, comprehensive consideration of the above first-class Code features can quickly improve the Code quality, improve the ability to write Code, etc.

 

When the Code Review

The ability to make simple judgments about bad code is required

In addition to understanding the features of first-class Code, you need to be able to make simple judgments about bad Code during Code Review. In general, bad code has the following characteristics:

 

① Code that can’t be understood in 5 minutes.

Code that can’t be read quickly must have a problem and can be thrown back to the programmer to fix. In general, a function cannot operate more than 6 steps. If this number is exceeded, the encoding logic needs to be readjugged.

② Code that requires thinking to understand.

Good code is a no-brainer, even in comments.

③ Code that requires scrolling back and forth to understand.

Good code is often a complete piece of logic in one screen.

④ Code with no empty lines or comments.

In Code Review, it is found that the Code that cannot use paragraphs and cannot write comments is definitely not the Code written by a good programmer. You can directly call back to the coder for correction.

 

Notes for Code Review

① When necessary, both sides of review shall communicate face to face.

Face-to-face communication is not just face-to-face communication, but also cloud sharing, phone calls, video communication, etc. During communication, background and key points should be explained to facilitate understanding. Design documentation should be provided when necessary.

② The owner system should be established for key modules.

All submitted code must be approved by owner. The owner shall master the overall situation and establish a clear responsibility relationship.

The problems found in the inspection should be pursued to the end.

④ Pay attention to details. Every line of submitted code is checked.

⑤ Take small steps to Code Review. Do not submit too much code to review each time to reduce complexity. In special cases, such as the construction of a new module, it is best to do it gradually, with multiple commits.

Set aside enough time for Code Review. The time of Code Review VS Coding can sometimes reach 1:1. Take into account that sometimes big changes will be made, plan your workload scientifically, and try to avoid time reversals.

The number of review code should not be too much every day.

 

Steps for Code Review

 

The steps of Code Review are as follows:

Step1: look at the whole system first

Do not delve into details, browse the overall picture of the system, clear the logic of module division, the relationship between modules, how to constitute the whole system, etc.

Step2: enter the module level

Similarly, without going into details, browse the whole picture of the module, judge whether the module segmentation is reasonable, clarify the logic of the module, and clarify the key data, key classes and functions.

Step3: clarify the logic inside the class and function.

Step4: go into details.

Such as Layout, naming, etc. Human factors

In addition to Code issues, there are also some human factors in the Code Review process, such as:

(1) the QA personnel

A good QA person will not only find bugs in the system, but will also question or ask for product requirements, challenge or improve the architecture and implementation of the system.

(2) the Code Reviewer

A good code reviewer will not only point out problems on the surface of the code, but also check the quality of the system requirements analysis, the soundness of the interface or function definition, the soundness of the module partition, the soundness of the key mechanism of the system, and so on.

Example: Code Review of Python Code

Taking Python as an example, take a look at the details of Code Review from two dimensions: the Python coding specification and the partial description of the Python programming specification. These Code Review details are basically the same in other languages.

 

The Python coding specification

(1) Write beautiful code.

(2) The code should be clear and direct, not implicit.

(3) the code should be concise, one function can achieve the function of not writing two functions.

(4) More esoteric code than complex code. Code can be esoteric, but not overly complex.

(5) The code should be flat, not layer upon layer of nesting.

(6) The code should be reasonably spaced.

(7) Code readability is very important.

(8) The code should be universal. Avoid code particularity as far as possible, with the most concise and universal code to achieve.

(9) The code should be practical.

(10) Pay attention to all errors found.

(11) Clear code logic. In the face of ambiguity and confusion, we refuse to guess. When reading or writing code, don’t make “as if,” “could,” or “as if.” When a piece of code is difficult to understand, there is something wrong with the code.

12. Write code for action.

(13) The code implementation method should be concise. If a method is hard to explain, it means there is something wrong with the method.

(14) Pay attention to the use of namespaces.

 

A partial description of the Python programming specification

The Python programming specification has nine dimensions.

(1) Module division

We have to have a concept of modules, which are the basis of the whole system.

① A.py file is a module.

② Module division is very important for long-term maintenance of software.

③ Each module should have a specific function.

For example: configuration file reading, web file writing, web file parsing, a memory data table, a crawl thread and so on.

④ It is a common mistake to write multiple independent modules into a. Py file. From the perspective of Code Review, the first thing is to see whether the modules are segmtioned correctly.

(2) Data encapsulation

In Code Review, pay attention to whether data is encapsulated.

(3) import

Import Do not use the from XXX Import YYy syntax to Import classes or functions. Do not use methods like from XXX import *. The goal is to make it easy to identify the source of the use of external variables or functions in your code.

If you use forbidden syntax, it makes it much harder to determine the source, and harder to read the code.

In Code Review, if such a situation occurs, the Code will be timely called back to the programmer for correction.

(4) abnormal

When handling exceptions, note the following:

① Use of exceptions

Before using exceptions, understand the behavior of exceptions in detail. Do not actively throw an exception, use the return value. If you must throw an exception, you need to comment it out.

(2) Obtain the exception forcibly

Except is disallowed unless an Exception is rethrown: Catching all exceptions is not recommended, Exception or StandardError.

In practice, it is recommended that as little code in a try as possible to avoid catching unexpected exceptions and hiding real errors. The bottom line is to at least print a log of the exception, rather than capture it and pass it.

When handling exceptions, try to catch specific exceptions for specific operations.

Common mistakes are: First, do not catch exceptions for IO and other operations. Second, the anomaly capture area is very large.

③ Return value of the function

If a function throws an exception, it needs to be specified in the comment of the function.

During Code Review, attention should be paid to the above problems, and they should be returned to the programmer for correction in time.

(5) Constructor

There are a few things to note about constructors:

1) specification:

Class constructors should be as simple as possible and should not contain operations that might fail or be too complex.

(2) reading:

A common mistake in constructors is not being able to determine or catch an exception.

(6) Return value of the function

There are a few things to note about function return values:

1) specification:

The return value of the function must be less than or equal to 3. Returns of more than three values must be wrapped in named forms such as class/namedtuple/dict.

(2) reading:

A. Most of the time errors are made because many people do not think and design the semantics of functions.

Function description involves three elements: function description, incoming parameter description and return value description.

Each function should have sufficiently explicit semantics. Based on the semantics of a function, there are three types of return values:

First type: In a “logical judgment” function, it returns a Boolean value — True or False, meaning “True” or “False”.

The second type: in “operational” functions, as an action, returns the result of success or failure — OK or ERROR.

Third type: in a “get data type” function, return a “data” or “no data/failed to get data”.

B. In addition, the function needs to have a return value, in the case of true or false, reflected in the return value.

C. Another problem is that Python’s data formats don’t need to be defined and are too flexible. When the program scale becomes larger and the maintenance cycle becomes longer, it will be extremely difficult to maintain later.

The solution is as follows: Write more comments, write clear return value description, parameter description.

In Code Review, if the Code is not clearly commented, be sure to call back to the programmer for correction and annotation.

(7) Code length

There are a few things to note about code length:

① Each line must contain no more than 120 characters. Avoid line breaks appearing on the terminal display.

② The length of the function shall not exceed 100 lines. Too long a function can make it difficult to understand the logic of the function. Python functions should be limited to between 30 and 40 lines.

In Code Review, the Code is too long, so it is suggested to call back to the programmer for correction.

(8) Blank line, space

There are a few things to note about blank lines and Spaces:

1. A blank line

There are two blank lines between the file and the definition. Such as classes or global functions. Class methods are separated by an empty line.

(2) the space

Commas, semicolons, and colons are preceded by no space and followed by a space. All binary operators are preceded by a space.

In Code Review, pay attention to blank lines and Spaces. Blank lines and Spaces are not optional. Blank lines and Spaces are present for readability. Hard to read the code, all call back to the programmer for correction.

(9) Notes

There are a few things to note about comments:

A special feature of comments in Python is docString, which is distinguished from the “#” note.

The relevant specifications are:

① When using docString to describe the Module, function, class, and method interfaces, docString must be enclosed in three double quotes.

② The external interface must be described by docString. The internal interface decides whether to write docString or not as the case may be.

(3) The docString description of the interface at least includes function introduction, parameters, and return values. If an exception can be thrown, you must use comments to indicate it.

④ Each document must have a document declaration, which must include the following information: copyright notice, function and purpose introduction, modifier and contact information.

In Code Review, if the Code does not meet the above specifications, call back to the programmer in time for correction.

 

How to be a good Reviewer

 

The quality of code review is directly related to the reviewer’s code capability. The poor quality of code reviews is a reflection of the reviewer’s code. If you can’t write code as a code reviewer, admit the truth and keep improving your code.

Here are some learning materials to help you learn.

① Books on code: The Art of Writing Readable Code, The Code Clean Way.

Comprehensive books: Code Book, 201 Principles of Software Development.

③ Others: The Art of Code, Python Good Coder Exam guide.

The company’s measures for Code Review

 

1. Establish an efficient and operational code review mechanism to improve code quality and reduce code review costs.

① Platform based: ICode + Bugbye

(2) Code check rules are classified into ERROR, WARNING, and ADVICE.

③ Optimization of code detection rules is driven by statistical data.

2. Inspect the Code Review of the project through engineering capability map.

3. All Code Review activities are based on icODE platform. Good tools can help with code reviews

Click to enter for more technical information ~~