PHP程式碼註解小細節

程式碼註釋，可以說是比程式碼本身更重要。告誡新人，一定要養成寫註釋的習慣，否則只能是損人不利己。這裡有一些方法可以確保你寫在程式碼中的註解是友善的，總結起來就是"5要與3不要"
一、不要重複閱讀者已經知道的內容（×）

一些光看方法名，光看程式碼就能看出來功能的就沒必要寫註釋，

// 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'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可以為你檢查拼字。如果沒有這個功能，那就去下載插件，自己動手！
七、要多多練習（√）
熟能生巧。試著寫一些有用的註釋，可以問其他開發人員你的註釋是否有用。隨著時間的推移，你會慢慢懂得怎樣才算是友善的註釋。
八、要檢閱別人的註解（√）
在程式碼審查時，我們傾向於忽略查看註解。不要怕要求更多的註釋，你應該提出質疑。如果每個人都養成寫好註解的好習慣，那麼世界將會更美好。
九、對註釋一定要知道的的精華總結

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