Code Review Checklist

左按：當年須要一份詳細的代碼評審清單做參考，翻譯了此文。

版權聲明：本文爲博主原創文章，未經博主容許不得轉載。

 

目錄(?)[-]

1. General Code Smoke Test 通用測試
2. Comments and Coding Conventions 註釋和代碼風格
3. Error Handling  錯誤處理
4. Resource Leaks 資源泄漏
5. Thread Safeness  線程安全性
6. Control Structures  控制結構
7. Performance 性能
8. Functions
9. Bug Fixes Bug修復
10. Math 數學考量

 

如下是流傳的code review檢查表，我不揣冒昧，爲節省你們時間，翻譯以下。

不當之處不免，故英文保留。

 

但願能夠給各位眼下以致未來的工做都有所幫助。:)

Terry 2003/12/18

 

Code Review Checklist

---

如下是用於開發人員代碼review的 Macadamian's指南 . 在代碼提交控制前，它們應該按照如下的規則檢查。
咱們公開這份檢查表是但願給任何開發部門的同行代碼評審提供一個簡要的參考。你能夠直接按本表開始評審，固然，更好的辦法是
按照開發實際做出修改後使用。

目錄
  General Code Smoke Test 通用測試
  Comments and Coding Conventions 註釋和代碼風格
  Error Handling 錯誤處理
  Resource Leaks 資源泄漏
  Control Structures 控制結構
  Performance 性能
  Functions 函數
  Bug Fixes bug修復
  Math 數學

General Code Smoke Test 通用測試

Does the code build correctly?
No errors should occur when building the source code. No warnings should be introduced by changes made to the code.

代碼能夠正確編譯：編譯代碼時應無錯誤。

Does the code execute as expected?
When executed, the code does what it is supposed to.

代碼是否像預期結果那樣執行？

Do you understand the code you are reviewing?
As a reviewer, you should understand the code. If you don't, the review may not be complete, or the code may not be well commented.

你理解正在review(評審)的代碼了嗎？做爲一個評審者，你應該理解這些代碼；不然將致使評審不充分或效果不太好。

Has the developer tested the code?
Insure the developer has unit tested the code before sending it for review. All the limit cases should have been tested.

確保開發者本人已經測試過代碼。在提交評審前，確保開發者已經完成了代碼的單元測試。全部可能的狀況應該測試。

Comments and Coding Conventions 註釋和代碼風格

Does the code respect the project coding conventions?
Check that the coding conventions have been followed. Variable naming, indentation, and bracket style should be used.

代碼是否遵循項目的編碼風格？檢查編碼風格是否已經遵循，好比變量命名、縮排、括號風格等。

Does the source file start with an appropriate header and copyright information?
Each source file should start with an appropriate header and copyright information. All source files should have a comment block describing the functionality provided by the file.

源代碼文件已適當的頭和版權信息開始。

Are variable declarations properly commented?
Comments are required for aspects of variables that the name doesn't describe. Each global variable should indicate its purpose and why it needs to be global.

變量聲明是否有合適的註釋。尤爲是全局變量，須要註明聲明爲全局的目的以及原因。

Are units of numeric data clearly stated?
Comment the units of numeric data. For example, if a number represents length, indicate if it is in feet or meters.

數值數據塊有否明確描述。好比，若是一個數字表明長度，應標明單位是英尺仍是米。

Are all functions, methods and classes documented?
Describe each routine, method, and class in one or two sentences at the top of its definition. If you can't describe it in a short sentence or two, you may need to reassess its purpose. It might be a sign that the design needs to be improved.

全部的函數、方法和類都已正式描述。在定義程序、方法、類之前，用一兩句簡短的話描述它們。
若是不能在一兩句話以內描述清楚，應該從新考慮它的目的；這也是須要改進設計的一個信號。

Are function parameters used for input or output clearly identified as such?
Make it clear which parameters are used for input and output.

全部函數的參數列表是否已經明確表示？

Are complex algorithms and code optimizations adequately commented?
Complex areas, algorithms, and code optimizations should be sufficiently commented, so other developers can understand the code and walk through it.

複雜算法和代碼優化 須要足夠的註釋。以確保開發人員能夠理解並審覈。

Does code that has been commented out have an explanation?
There should be an explanation for any code that is commented out. "Dead Code" should be removed. If it is a temporary hack, it should be identified as such.

註釋掉的代碼是否有解釋？"Dead Code" 必須刪除。

Are comments used to identify missing functionality or unresolved issues in the code?
A comment is required for all code not completely implemented. The comment should describe what's left to do or is missing. You should also use a distinctive marker that you can search for later (For example: "TODO:francis").

缺乏的函數功能、沒有徹底解決的問題須要註釋表示。註釋要描述剩下的工做以及缺乏的東西。最好加一個標記以便未來查找，例如「TODO:fancis」。

Error Handling  錯誤處理

Are assertions used everywhere data is expected to have a valid value or range?
Assertions make it easier to identify potential problems. For example, test if pointers or references are valid.

在須要有效 值或範圍 的任何地方使用斷言。如指針和引用。

Are errors properly handled each time a function returns?
An error should be detected and handled if it affects the execution of the rest of a routine. For example, if a resource allocation fails, this affects the rest of the routine if it uses that resource. This should be detected and proper action taken. In some cases, the "proper action" may simply be to log the error.

函數返回時，全部出錯恰當的處理。若是該錯誤影響到接下來程序的執行（好比資源分配失敗），一般能夠簡單的寫log文件來處理。

Are resources and memory released in all error paths?
Make sure all resources and memory allocated are released in the error paths.

在出錯時，確保全部資源包括內存 分配被釋放。

Are all thrown exceptions handled properly?
If the source code uses a routine that throws an exception, there should be a function in the call stack that catches it and handles it properly.

全部拋出的異常恰當處理。若是拋出了異常，應該有對應合適的catch函數。

Is the function caller notified when an error is detected?
Consider notifying your caller when an error is detected. If the error might affect your caller, the caller should be notified. For example, the "Open" methods of a file class should return error conditions. Even if the class stays in a valid state and other calls to the class will be handled properly, the caller might be interested in doing some error handling of its own.

發生錯誤時，最好可以通知調用者。

Has error handling code been tested?
Don't forget that error handling code that can be defective. It is important to write test cases that exercise it.

錯誤處理 的代碼是否已經測試過。

Resource Leaks 資源泄漏

Is allocated memory (non-garbage collected) freed?
All allocated memory needs to be freed when no longer needed. Make sure memory is released in all code paths, especially in error code paths.

分配的資源都被釋放了嗎？全部的資源（內存）在不需使用時都應釋放。特別注意異常條件下的狀況。

Are all objects (Database connections, Sockets, Files, etc.) freed even when an error occurs?
File, Sockets, Database connections, etc. (basically all objects where a creation and a deletion method exist) should be freed even when an error occurs. For example, whenever you use "new" in C++, there should be a delete somewhere that disposes of the object. Resources that are opened must be closed. For example, when opening a file in most development environments, you need to call a method to close the file when you're done.

即便發生異常，全部的對象（數據鏈接，Sockets和文件等）是否都已釋放。資源打開對應就該有關閉。

Is the same object released more than once?
Make sure there's no code path where the same object is released more than once. Check error code paths.

不要重複釋放同一對象。檢查異常處理代碼的狀況。

Does the code accurately keep track of reference counting?
Frequently a reference counter is used to keep the reference count on objects (For example, COM objects). The object uses the reference counter to determine when to destroy itself. In most cases, the developer uses methods to increment or decrement the reference count. Make sure the reference count reflects the number of times an object is referred.

確保 代碼與引用計數（reference counting）保持同步。
P.S.: STL中容許使用SmartPointer,而不能自動實現引用計數（請參見開放源代碼 Boost 庫中的 shared_ptr 類，或者參見STL中的更加簡單的 auto_ptr 類）。COM中有相關的應用。

Thread Safeness  線程安全性

Are all global variables thread-safe?
If global variables can be accessed by more than one thread, code altering the global variable should be enclosed using a synchronization mechanism such as a mutex. Code accessing the variable should be enclosed with the same mechanism.

全部全局變量都是線程安全的。若是容許一個以上線程訪問全局變量，應該採用互斥之類的機制。

Are objects accessed by multiple threads thread-safe?
If some objects can be accessed by more than one thread, make sure member variables are protected by synchronization mechanisms.

確保多線程安全存取（訪問）對象。

Are locks released in the same order they are obtained?
It is important to release the locks in the same order they were acquired to avoid deadlock situations. Check error code paths.

解鎖順序與它們得到的順序相同，以免死鎖狀況發生。

Is there any possible deadlock or lock contention?
Make sure there's no possibility for acquiring a set of locks (mutex, semaphores, etc.) in different orders. For example, if Thread A acquires Lock #1 and then Lock #2, then Thread B shouldn't acquire Lock #2 and then Lock #1.

是否存在可能的死鎖或線程爭搶資源？

Control Structures  控制結構

Are loop ending conditions accurate?
Check all loops to make sure they iterate the right number of times. Check the condition that ends the loop; insure it will end out doing the expected number of iterations.

循環結束條件是否精確？檢查遞增的次數、循環結束條件。

Is the code free of unintended infinite loops?
Check for code paths that can cause infinite loops. Make sure end loop conditions will be met unless otherwise documented.

代碼不要陷入無窮循環。檢查可能致使無窮循環的代碼路徑。

Performance 性能

Do recursive functions run within a reasonable amount of stack space?
Recursive functions should run with a reasonable amount of stack space. Generally, it is better to code iterative functions.

遞歸函數在合理的堆棧空間內運行。

Are whole objects duplicated when only references are needed?
This happens when objects are passed by value when only references are required. This also applies to algorithms that copy a lot of memory. Consider using algorithm that minimizes the number of object duplications, reducing the data that needs to be transferred in memory.

全體對象拷貝是否在須要引用時進行？儘可能減小須要傳送的內存數據。

Does the code have an impact on size, speed, or memory use?
Can it be optimized? For instance, if you use data structures with a large number of occurrences, you might want to reduce the size of the structure.

代碼是否影響規模、速度和內存使用？可否再優化？

Are you using blocking system calls when performance is involved?
Consider using a different thread for code making a function call that blocks.

Is the code doing busy waits instead of using synchronization mechanisms or timer events?
Doing busy waits takes up CPU time. It is a better practice to use synchronization mechanisms.

Was this optimization really needed?
Optimizations often make code harder to read and more likely to contain bugs. Such optimizations should be avoided unless a need has been identified. Has the code been profiled?

Functions

Are function parameters explicitly verified in the code?
This check is encouraged for functions where you don't control the whole range of values that are sent to the function. This isn't the case for helper functions, for instance. Each function should check its parameter for minimum and maximum possible values. Each pointer or reference should be checked to see if it is null. An error or an exception should occur if a parameter is invalid.

Are arrays explicitly checked for out-of-bound indexes?
Make sure an error message is displayed if an index is out-of-bound.

Are functions returning references to objects declared on the stack?
Don't return references to objects declared on the stack, return references to objects created on the heap.

Are variables initialized before they are used?
Make sure there are no code paths where variables are used prior to being initialized. If an object is used by more than one thread, make sure the object is not in use by another thread when you destroy it. If an object is created by doing a function call, make sure the object was created before using it.

Does the code re-write functionality that could be achieved by using an existing API?
Don't reinvent the wheel. New code should use existing functionality as much as possible. Don't rewrite source code that already exists in the project. Code that is replicated in more than one function should be put in a helper function for easier maintenance.

Bug Fixes Bug修復

Does a fix made to a function change the behavior of caller functions?
Sometimes code expects a function to behave incorrectly. Fixing the function can, in some cases, break the caller. If this happens, either fix the code that depends on the function, or add a comment explaining why the code can't be changed.

修復Bug是否致使調用函數發生變化。

Does the bug fix correct all the occurrences of the bug?
If the code you're reviewing is fixing a bug, make sure it fixes all the occurrences of the bug.

對Bug的修復是否已經改正了全部併發可能的錯誤。（不能引入新的Bug）

Math 數學考量

Is the code doing signed/unsigned conversions?
Check all signed to unsigned conversions: Can sign completion cause problems? Check all unsigned to signed conversions: Can overflow occur? Test with Minimum and Maximum possible values.

代碼有否進行有符號/無符號的轉換？有符號-〉無符號，符號有否出現問題？無符號-〉有符號，是否發生溢出？用最大、最小值來測試。

 

如下是流傳的code review檢查表，我不揣冒昧，爲節省你們時間，翻譯以下。
不當之處不免，故英文保留。 但願能夠給各位眼下以致未來的工做都有所幫助。
Terry 2003/12/18