花五分鐘把代碼註釋也規範一哈子？

序

【註釋】從技術上來講沒有對錯，理論上，你想怎麼寫就怎麼寫，你愛怎麼寫就怎麼寫！

但它確實也會對咱們形成影響，尤爲是在多人協同開發的系統中。雜亂的註釋也會讓你或你的隊友頭疼~

因此，咱們須要規範一下注釋。那什麼纔是好的註釋呢？咱們先來看看什麼是很差的註釋！

註釋冗餘

咱們每每會寫一段註釋來講明「這是什麼」。好比：

// Find all the users
let users = userHelper.findAll();

// Add score to each user
users.forEach((user) => {
	user.score++;
}
						
// Return the users
return users;
複製代碼

可是這段代碼自己的意思就很清楚了，再附上註釋就有點多餘了。

因此咱們應該將其剔除。

let users = userHelper.findAll();

users.forEach((user) => {
	user.score++;
}
						
return users;
複製代碼

那麼，這段代碼是否是就方便閱讀了呢？其實，我們還能更進一步：

let users = userHelper.findAll();
userHelper.incrementScoreForAll(users);						
return users;
複製代碼

這樣你感受如何？相比於最開始的那段代碼，這段是否是就看得舒舒服服？

因此，可讀的代碼比可讀的註釋更重要。優先考慮讓你的代碼說話，實在不行，再附上簡短、清晰的註釋。

註釋未更新

// Find all users
let users = userHelper.findBanned();

// Give each user 100 extra score
users.forEach((user) => {
	user.score = 0;
}

return users;
複製代碼

咱們有時候會發現註釋和代碼並不匹配，好比這裏爲用戶設置分數的操做。代碼中是 0 分，註釋倒是 100 分。

致使出現這種狀況有多種可能：

1. 咱們老是在從其它地方複製代碼，有時也會一併複製註釋，而後在爲己所用的過程當中，修改了代碼卻沒有修改對應的註釋。
2. 咱們同時也在不斷的根據產品需求調整代碼（好比此處設置分值），修改代碼也可能會忘記修改以前寫的註釋。

怎麼辦？讓咱們來看看優解：

// userHelper.js
function updateScoreForUsers(score, users) {
  users.forEach((user) => {
	  user.score += score;
  }
}

// Code 1: punish banned users
let users = userHelper.findBanned();
userHelper.updateScoreForUsers(users, -100);
return users;

// Code 2: give everybody 1 extra score
let users = userHelper.findAll();
userHelper.updateScoreForUsers(users, 1);
return users;
複製代碼

這樣寫將設置分數的邏輯封裝成函數進行了抽離，功能更強了，也更易於閱讀了。

如今，咱們能夠在多種狀況下重複調用它，且沒必要擔憂註釋未及時更新的問題了。

註釋太長

請問若是是這樣的註釋，你還有信心整個完整讀下來嗎？即便你是一個勇敢堅強的技術人，讀下來也會消耗不少時間吧？這樣低效率的事確定不是咱們想要的。

// userHelper.js
/**
 * Mass updates the user score for the given a list of user
 * The score will be updated by the amount given in the parameter score
 * For example, if the parameter score is 5, the users will all receive 5 extra score
 * But if the score is negative, it can also be used. In that case, the score will be decreased by 5.
 * If you set score as 0, then this method will be useless as nothing will be updated.
 * If you set the score as a non number value, the function will not do anything and return false
 * just to ensure the score is not messed up after updating it with a non-number value
 * Try to avoid using non-number values in the score parameter as this should not be used like that
 * If you do however choose to use Infinity in the score argument, it will work, because Infinity is considered as a number in JavaScript
 * If you set the score to Infinity, all the users score will become Inifinity, because n + Infinity where n is a number, will always result in Infinity
 * Regarding the users, make sure this is an array! If it is not an array, we will not process the users score,
 * then our method will simply return false instead and stop processing
 * Also make sure the users array is a list of actual user objects, we do not check this, but make sure the object has all the required fields as expected
 * especially the score object is important in this case.
 * @returns {boolean} Returns true if successful, false if not processed.
 */
function updateScoreForUsers(score, users) {
  if (isNaN(score) || typeof users !== 'array') { return false; }
  
  users.forEach((user) => {
	  user.score += score;
  }
                
  return true;
}
複製代碼

因此，請確保你的註釋不要太長。有那麼多想說的，能夠寫文檔、能夠寫文章，不要寫註釋~

簡單直接是最迷人的！

註釋過短

這是另外一個極端的例子，可是它確實源自於現實的開發項目中。

// userHelper.js
/**
 * Update score
 * @returns {boolean} result
 */
function updateScoreForUsers(score, users) {
  if (isNaN(score) || typeof users !== 'array') { return false; }
  
  users.forEach((user) => {
	  user.score += score;
  }
                
  return true;
}
複製代碼

此段代碼註釋只是說明了返回值，可是更爲關鍵的傳參並未做出釋義。顯得有些尷尬~

若是你決定註釋，那就不要只寫一半。請儘可能準確、完整、乾淨的將其寫出。從長期來看，你必定會從中受益。

好的註釋

好的註釋就是告訴你們你爲何要進行註釋！

好比：

// userHelper.js
function updateScoreForUsers(score, users) {
  users.forEach((user) => {
    user.score += score;
    
    // VIPs are promised 500 extra score on top
    if (user.type == 'VIP') {
      user.score += 500;
    }
  }
                
  return true;
}
複製代碼

此例中咱們能夠明白 VIP 用戶是被產品要求多加 500 分值的。這樣其它開發就不會對此產生疑惑。

若是代碼由多個團隊維護，簡單直接的小標註就更爲必要了！

小結

註釋在代碼中扮演很重要的角色。本瓜還記得大學老師說：註釋應該佔代碼的三分之一。

咱們都有不一樣的註釋習慣，可是也應該有一個基本的指導：

1. 註釋應當簡短、清晰，長篇大論稍邊邊。
2. 告訴你們你 「爲何」 寫這個註釋，而不是告訴你們這段代碼 「是什麼」！「是什麼」 應該交給代碼自己去解釋。這個最爲關鍵！
3. 保持你的註釋持久維護，也就是記得及時更新和與代碼匹配。

代碼可讀就是最好的註釋。

以上！

撰文不易，點贊鼓勵。討論留言，攜手向前。★,°:.☆(￣▽￣)/$:.°★ 。

求一波關注，個人公衆號：【掘金安東尼】，牛年持續更新~