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

简介: 从技术上来说没有对错,理论上,你想怎么写就怎么写,你爱怎么写就怎么写!但它确实也会对我们造成影响,尤其是在多人协同开发的系统中。杂乱的注释也会让你或你的队友头疼~所以,我们需要规范一下注释。那什么才是好的注释呢?我们先来看看什么是不好的注释!

image.png



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


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


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


注释冗余



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


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


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

以上!


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

求一波关注,我的公众号:【掘金安东尼】,牛年持续更新~


相关文章
|
6月前
|
前端开发 JavaScript
工作中代码书写规范
前端代码规范增进代码整洁与团队协作,降低维护成本。包括代码规范、风格和注释建议:选择编程语言对应的编码规范,统一命名、缩进和换行规则;注重代码风格的一致性、简洁性和可配置性;注释要简洁明了,位于关键位置。通过制定规范文档、使用代码检查工具、定期代码审查和鼓励改进来执行规范,提升团队效率和代码质量。
69 0
|
6月前
|
自然语言处理 算法 Java
C/C++ 程序员编程规范之注释
C/C++ 程序员编程规范之注释
182 1
|
6月前
|
设计模式 算法 前端开发
有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
56 0
|
4月前
codereview开发问题之CodeReview中如何判断注释问题如何解决
codereview开发问题之CodeReview中如何判断注释问题如何解决
|
5月前
|
算法 安全 编译器
【简洁的代码永远不会掩盖设计者的意图】如何写出规范整洁的代码
【简洁的代码永远不会掩盖设计者的意图】如何写出规范整洁的代码
52 1
|
6月前
|
前端开发 测试技术
代码注释怎么写:让你的代码更易维护
在编程中,有一种无声的艺术,那就是代码注释。这可能看起来微不足道,但其实非常关键。它不仅有助于他人理解你的代码,也是自我表达的一种方式。
|
6月前
|
设计模式 算法 程序员
如何写出好的代码注释?
作为程序员,想必大家在日常开发中必写注释,而且在软件开发过程中,给代码写注释是一项至关重要的工作,也是一名合格的程序员该具备的编程素养。恰当的注释可以提高代码的可读性和可维护性,方便其他人理解熟悉和修改代码,但是不恰当或过度的注释可能会导致混乱和误导,会起到适得其反的作用。那么本文就来分享一些关于如何正确地给代码写注释的方法和指导原则,并提供一些减少注释但仍能让他人理解代码的方法。
145 3
如何写出好的代码注释?
|
测试技术
你觉得哪些不规范的编程行为最让人头疼?
你觉得哪些不规范的编程行为最让人头疼?
78 1
|
人工智能 自然语言处理 Java
提高代码可读性的秘诀:注释的重要性
A:你写代码怎么连注释都不加? B:老大为什么要加注释? A:你不加注释,你怎么知道我能看懂你的代码? B:遇到问题你找到就可以了啊? A:那你哪天生病了请假了闹情绪了离职了,公司怎么办? B:我现在反正没觉得有什么问题,我对公司也很满意,安心啦! 又是00后整顿职场的一段精彩演绎。不可置否,在实际的软件开发过程中,确实有很多开发人员依然不愿意写注释认为这会浪费时间,或者自认为他们的代码足够清晰,不需要额外的解释。但这种想法too young too simple,代码注释对于项目的质量和效率有着深远的影响,在软件开发中的重要性不容小觑。
关于代码重构你应该知道的内容
关于代码重构你应该知道的内容
158 0
关于代码重构你应该知道的内容