首頁 Java java教程 程式碼註解中的5要與3不要

程式碼註解中的5要與3不要

Nov 30, 2016 am 09:55 AM
程式碼註解

  程式碼註釋,可以說是比程式碼本身更重要。這裡有一些方法可以確保你寫在程式碼中的註解是友善的:

 不要重複閱讀者已經知道的內容

  能明確說明程式碼是做什麼的註解對我們是沒有幫助的。

// If the color is red, turn it green
if (color.is_red()) {
  color.turn_green();
}
登入後複製

 要註釋說明和歷史

  如果程式碼中的業務邏輯以後可能需要更新或更改,那就應該留下註釋:)

/* The API currently returns an array of items
even though that will change in an upcoming ticket.
Therefore, be sure to change the loop style here so that
we properly iterate over an object */
 
var api_result = {items: ["one", "two"]},
    items = api_result.items,
    num_items = items.length;
 
for(var x = 0; x < num_items; x++) {
  ...
}
登入後複製

同一行的註釋不要寫得很長

🀎 『水平滾動條來閱讀註解更令開發人員髮指的了。事實上,大多數開發人員都會選擇忽略這類註釋,因為讀起來真的很不方便。

function Person(name) {
  this.name = name;
  this.first_name = name.split(" ")[0]; // This is just a shot in the dark here. If we can extract the first name, let&#39;s do it
}
登入後複製

要把長註解放在邏輯上面,短註解放在後面

  註解如果不超過120個字元那可以放在程式碼旁邊。否則,就應該直接把註解放到語句上面。

if (person.age < 21) {
  person.can_drink = false; // 21 drinking age
 
  /* Fees are given to those under 25, but only in
     some states. */
  person.has_car_rental_fee = function(state) {
    if (state === "MI") {
      return true;
    }
  };
}
登入後複製

不要為了註釋而添加不必要的註釋

  畫蛇添足的註釋會造成混亂。也許在學校裡老師教你要給所有語句加上註釋,這會幫助開發人員更好地理解。但這是錯的。誰要這麼說,那你就立刻給他個兩大耳刮鬍子。程式碼應該保持乾淨簡潔,這是毋庸置疑的。如果你的程式碼需要逐行解釋說明,那麼你最需要做的是重構。

if (person.age >= 21) {
  person.can_drink = true; // A person can drink at 21
  person.can_smoke = true; // A person can smoke at 18
  person.can_wed = true; // A person can get married at 18
  person.can_see_all_movies = true; // A person can see all movies at 17
  //I hate babies and children and all things pure because I comment too much
}
登入後複製
註解要拼字正確

  不要為程式碼註解中的拼字錯誤找藉口。 IDE可以為你檢查拼字。如果沒有這個功能,那就去下載插件,自己動手!

 要多多練習

  熟能生巧。試著寫一些有用的註釋,可以問其他開發人員你的註釋是否有用。隨著時間的推移,你會慢慢懂得怎樣才算是友善的註釋。

 要審查別人的註解

  在程式碼審查時,我們往往會忽略查看註解。不要怕要求更多的註釋,你應該提出質疑。如果每個人都養成寫好註解的好習慣,那麼世界將會更美好。

 總結

  註解是開發過程中非常重要的一部分,但我們不應該為了註解而註解。註解應該是有用的,簡潔的,應該是對程式碼的一種補充。註釋不應該用於逐行地解釋程式碼,相反,它應該用於解釋業務邏輯,推理以及對將來的啟示。


本網站聲明
本文內容由網友自願投稿,版權歸原作者所有。本站不承擔相應的法律責任。如發現涉嫌抄襲或侵權的內容,請聯絡admin@php.cn

熱AI工具

Undresser.AI Undress

Undresser.AI Undress

人工智慧驅動的應用程序,用於創建逼真的裸體照片

AI Clothes Remover

AI Clothes Remover

用於從照片中去除衣服的線上人工智慧工具。

Undress AI Tool

Undress AI Tool

免費脫衣圖片

Clothoff.io

Clothoff.io

AI脫衣器

Video Face Swap

Video Face Swap

使用我們完全免費的人工智慧換臉工具,輕鬆在任何影片中換臉!

熱門文章

<🎜>:泡泡膠模擬器無窮大 - 如何獲取和使用皇家鑰匙
3 週前 By 尊渡假赌尊渡假赌尊渡假赌
北端:融合系統,解釋
3 週前 By 尊渡假赌尊渡假赌尊渡假赌

熱工具

記事本++7.3.1

記事本++7.3.1

好用且免費的程式碼編輯器

SublimeText3漢化版

SublimeText3漢化版

中文版,非常好用

禪工作室 13.0.1

禪工作室 13.0.1

強大的PHP整合開發環境

Dreamweaver CS6

Dreamweaver CS6

視覺化網頁開發工具

SublimeText3 Mac版

SublimeText3 Mac版

神級程式碼編輯軟體(SublimeText3)

熱門話題

Java教學
1664
14
CakePHP 教程
1423
52
Laravel 教程
1318
25
PHP教程
1269
29
C# 教程
1248
24
公司安全軟件導致應用無法運行?如何排查和解決? 公司安全軟件導致應用無法運行?如何排查和解決? Apr 19, 2025 pm 04:51 PM

公司安全軟件導致部分應用無法正常運行的排查與解決方法許多公司為了保障內部網絡安全,會部署安全軟件。 ...

如何將姓名轉換為數字以實現排序並保持群組中的一致性? 如何將姓名轉換為數字以實現排序並保持群組中的一致性? Apr 19, 2025 pm 11:30 PM

將姓名轉換為數字以實現排序的解決方案在許多應用場景中,用戶可能需要在群組中進行排序,尤其是在一個用...

如何使用MapStruct簡化系統對接中的字段映射問題? 如何使用MapStruct簡化系統對接中的字段映射問題? Apr 19, 2025 pm 06:21 PM

系統對接中的字段映射處理在進行系統對接時,常常會遇到一個棘手的問題:如何將A系統的接口字段有效地映�...

IntelliJ IDEA是如何在不輸出日誌的情況下識別Spring Boot項目的端口號的? IntelliJ IDEA是如何在不輸出日誌的情況下識別Spring Boot項目的端口號的? Apr 19, 2025 pm 11:45 PM

在使用IntelliJIDEAUltimate版本啟動Spring...

如何優雅地獲取實體類變量名構建數據庫查詢條件? 如何優雅地獲取實體類變量名構建數據庫查詢條件? Apr 19, 2025 pm 11:42 PM

在使用MyBatis-Plus或其他ORM框架進行數據庫操作時,經常需要根據實體類的屬性名構造查詢條件。如果每次都手動...

Java對像如何安全地轉換為數組? Java對像如何安全地轉換為數組? Apr 19, 2025 pm 11:33 PM

Java對象與數組的轉換:深入探討強制類型轉換的風險與正確方法很多Java初學者會遇到將一個對象轉換成數組的�...

如何利用Redis緩存方案高效實現產品排行榜列表的需求? 如何利用Redis緩存方案高效實現產品排行榜列表的需求? Apr 19, 2025 pm 11:36 PM

Redis緩存方案如何實現產品排行榜列表的需求?在開發過程中,我們常常需要處理排行榜的需求,例如展示一個�...

電商平台SKU和SPU數據庫設計:如何兼顧用戶自定義屬性和無屬性商品? 電商平台SKU和SPU數據庫設計:如何兼顧用戶自定義屬性和無屬性商品? Apr 19, 2025 pm 11:27 PM

電商平台SKU和SPU表設計詳解本文將探討電商平台中SKU和SPU的數據庫設計問題,特別是如何處理用戶自定義銷售屬...

See all articles