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

1. 序
2. 註釋冗餘
3. 註釋未更新
4. 註釋太長
5. 註釋太短
6. 好的註釋
7. 小結
- 7.1. 相關文章

序

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

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

所以，我們需要規範一下注釋。那什麼才是好的註釋呢？我們先來看看什麼是不好的註釋！

註釋冗餘

我們往往會寫一段註釋來說明“這是什麼”。比如：

// 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 分。

導致出現這種情況有多種可能：

我們總是在從其它地方，有時也會一併複製註釋，然後在為己所用的過程中，修改了代碼卻沒有修改對應的註釋。
我們同時也在不斷的根據產品需求調整代碼（比如此處設置分值），修改代碼也可能會忘記修改之前寫的註釋。

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

// 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 分值的。這樣其它開發就不會對此產生疑惑。

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