花5分钟规范「代码注释」

【注释】从技术上来说没有对错,理论上,你想怎么写就怎么写,你爱怎么写就怎么写!

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

所以,我们需要规范一下注释。那什么才是好的注释呢?我们先来看看什么是不好的注释!

注释冗余

我们往往会写一段注释来说明“这是什么”。比如:

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

本文来自投稿,不代表重蔚自留地立场,如若转载,请注明出处:https://www.cwhello.com/35921.html

(0)
上一篇 2022年5月13日 23:01
下一篇 2022年5月13日 23:07

相关推荐

  • 机器学习|10种聚类算法详解及Python代码实现

    大家好,我是大雄。分享一篇关于聚类的文章,10种聚类介绍和Python代码。聚类或聚类分析是无监督学习问题。它通常被用作数据分析技术,用于发现数据中的有趣模式,例如基于其行为的客户群。有许多聚类算法可供选择,...

    2022年4月27日
    0380
  • 用 Python 从单个文本中提取关键字的四种超棒的方法

    本文将介绍四种关键字提取方法,分别为Rake、Yake、Keybert 和 Textrank。在上图展示的示例中,有文本标题和文章摘要,标准关键字(由作者在原始文章中定义)被标记为黄色。注意machine learning这个词并不明确,也...

    2022年4月27日
    0390
  • 号外!玩转Python字符串的7大秘籍

    字符串是Python中最常用、最基本的数据类型。Python对字符串的处理内置了很多高效的函数,在很多情况下,Python对字符串处理的效率要远高于其他编程语言。下面是我总结的常用的秘籍。欢迎大家一起学习~字符串赋值字...

    2022年4月27日
    0290
  • 机器学习:轻松掌握决策树模型

    决策树模型因为其特征预处理简单、易于集成学习、良好的拟合能力及解释性,是应用最广泛的机器学习模型之一。不同于线性模型【数学描述:f(W*X +b)】是通过数据样本学习各个特征的合适权重,加权后做出决策。决策树...

    2022年4月27日
    0240
  • 机器学习|调参方法分享(建议收藏!!!)

    有小伙伴催更了...今天给大家分享一下机器学习调参的几种方法。首次给大家介绍一下什么是调参。调参其实是为了找到更好更优的超参数,而超参数呢,是算法或者模型在开始学习之前设置值的初始参数。超参数是在建立模...

    2022年4月27日
    0270
  • Python中的6个三维可视化工具

    Python拥有很多优秀的三维图像可视化工具,主要基于图形处理库WebGL、OpenGL或者VTK。这些工具主要用于大规模空间标量数据、向量场数据、张量场数据等等的可视化,实际运用场景主要在海洋大气建模、飞机模型设计、桥...

    2022年4月27日
    0240
  • 又一大厂裁员!当天粗暴通知赔偿N+1?小红书回应了...

    大厂们陆陆续续都在裁员,这次是轮到了小红书?近日,小红书被曝裁员的消息冲上微博热搜榜。据悉,相关员工在社交平台上爆料称,裁员全面启动,当天被通知last day。据脉脉上的相关爆料,此次整体裁员20%,先从试用...

    2022年4月27日
    0250
  • Python3知识点大全!菜鸟必备,建议收藏

    《Python3自学速查手册》。这是我见过的知识点最全面,匹配案例最多的合集。每个函数均附有详细描述、语法参考、参数、返回值以及案例。共计324页内容。堪称Python3大字典,有书签更方便查,哪里不会点哪里。是自学...

    2022年4月27日
    0300

发表评论

您的电子邮箱地址不会被公开。

您看到的还是重蔚自留地。只是我们升级啦!