花五分钟把代码注释也规范一哈子？

序

【注释】从技术上来讲没有对错，理论上，你想怎么写就怎么写，你爱怎么写就怎么写！

但它确实也会对咱们形成影响，尤为是在多人协同开发的系统中。杂乱的注释也会让你或你的队友头疼~

因此，咱们须要规范一下注释。那什么才是好的注释呢？咱们先来看看什么是很差的注释！

注释冗余

咱们每每会写一段注释来讲明“这是什么”。好比：

// 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. 保持你的注释持久维护，也就是记得及时更新和与代码匹配。

代码可读就是最好的注释。

以上！

撰文不易，点赞鼓励。讨论留言，携手向前。★,°:.☆(￣▽￣)/$:.°★ 。

求一波关注，个人公众号：【掘金安东尼】，牛年持续更新~