什么是好的代碼注釋?

Use a comment when it is infeasible to make your code self-explanatory.
當你的代碼不容易自我解釋邏輯的時候,才需要寫注釋。

如果你發現自己的代碼可以自我解釋邏輯,則不需要添加注釋。
例如下面代碼中的注釋都是沒有意義的:

// Get all users.
userService.getAllUsers();

// Check if the name is empty.
if (name.isEmpty()) { ... }

如果你發現自己的代碼不容易自我解釋邏輯,首先可以嘗試修改代碼,讓它變得容易自我解釋邏輯。

示例

例如下面這樣一段計算最終價格的代碼:

finalPrice = (numOfItems * itemPrice) - max(20, numOfItems) * 0.1;

其他人并不懂 max(20, numOfItems) * 0.1 是什么意思,因此你第一想法肯定是加上注釋,例如:

// Subtract discount from price.
finalPrice = (numOfItems * itemPrice) - max(20, numOfItems) * 0.1;

其實更好的辦法是引入一個可以自我解釋的變量,例如:(這樣其他人一眼也能看懂)

price = numOfItems * itemPrice;
discount = max(20, numOfItems) * 0.1;
finalPrice = price -- discount;

示例

例如下面這樣一段過濾字符串數組的代碼:

for (String word : words) { ... }

其他人并不懂這一段的目的是什么,因此你第一想法肯定是加上注釋,例如:

// Filter offensive words.
for (String word : words) { ... }

其實更好的辦法是引入一個可以自我解釋的方法名,例如:(這樣其他人一眼也能看懂)

filterOffensiveWords(words);


String[] filterOffensiveWords(String[] words) {
  for (String word : words) { ... }
}

示例

使用更有意義的變量名,例如:
int width = ...; // Width in pixels.
我們可以使用 int widthInPixels = ...; 來取代注釋。

...持續更新...

?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發布,文章內容僅代表作者本人觀點,簡書系信息發布平臺,僅提供信息存儲服務。

推薦閱讀更多精彩內容

  • iOS編程規范0規范 0.1前言 為??高產品代碼質量,指導廣大軟件開發人員編寫出簡潔、可維護、可靠、可 測試、高效...
    iOS行者閱讀 4,496評論 21 35
  • 推薦文章:禪與 Objective-C 編程藝 前言 為??高產品代碼質量,指導廣大軟件開發人員編寫出簡潔、可維護、...
    WolfTin閱讀 2,807評論 0 1
  • 一. 為什么讀這本書 很多同行在編寫代碼的時候往往只關注一些宏觀上的主題:架構,設計模式,數據結構等等,卻忽視了一...
    隱身人閱讀 743評論 0 2
  • 緩存更新策略FIFO[First In First Out]。最先進入緩存的數據在緩存空間不足情況下最先清理出去L...
    Captain_tu閱讀 239評論 0 0
  • 和修姐相識已有整整二十一年了。記得那是1997年的8月底,高考失利進了教育學院學前藝術系,而她剛好是去學校再進修...
    跳跳糖zhz閱讀 337評論 0 1