序
【註釋】從技術上來說沒有對錯,理論上,你想怎麼寫就怎麼寫,你愛怎麼寫就怎麼寫!
但它確實也會對我們造成影響,尤其是在多人協同開發的系統中。雜亂的註釋也會讓你或你的隊友頭疼~
所以,我們需要規範一下注釋。那什麼才是好的註釋呢?我們先來看看什麼是不好的註釋!
註釋冗餘
我們往往會寫一段註釋來說明“這是什麼”。比如:
// 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 分值的。這樣其它開發就不會對此產生疑惑。
如果代碼由多個團隊維護,簡單直接的小標註就更為必要了!
小結
註釋在代碼中扮演很重要的角色。本瓜還記得大學老師說:註釋應該佔代碼的三分之一。
我們都有不同的註釋習慣,但是也應該有一個基本的指導:
- 註釋應當簡短、清晰,長篇大論稍邊邊。
- 告訴大家你 “為什麼” 寫這個註釋,而不是告訴大家這段代碼 “是什麼”!“是什麼” 應該交給代碼本身去解釋。這個最為關鍵!
- 保持你的註釋持久維護,也就是記得及時更新和與代碼匹配。
代碼可讀就是最好的註釋。
以上!
撰文不易,點贊鼓勵。討論留言,攜手向前。★,°:.☆( ̄▽ ̄)/$:.°★ 。
求一波關注,我的公眾號:【掘金安東尼】,牛年持續更新~