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

NO IMAGE

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

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

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

註釋冗餘

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

// 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. 保持你的註釋持久維護,也就是記得及時更新和與代碼匹配。

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

以上!

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

求一波關注,我的公眾號:【掘金安東尼】,牛年持續更新~

相關文章

Nginx——負載均衡、動靜分離介紹

摸魚小技巧之IDEA調試篇一

Flutter使用Riverpod+Retrofit構建MVVM開發模式

教你寫出高性能JavaScript