最近在看js的教程,然后看到里面所讲述的关于提升代码质量的文字,深受所启发,现将之摘抄下来便于回忆:

很棒的原则(如雷贯耳,听得我想remake):“如果代码不够清晰以至于需要一个注释,那么或许它应该被重写。”

关于提高代码质量的两个配方,分别是分解函数和创建函数

好的注释应该在什么地方

描述架构
对组件进行高层次的整体概括,它们如何相互作用、各种情况下的控制流程是什么样的……简而言之 —— 代码的鸟瞰图。

记录函数的参数和用法
例如:

/**
 * 返回 x 的 n 次幂的值。
 *
 * @param {number} x 要改变的值。
 * @param {number} n 幂数,必须是一个自然数。
 * @return {number} x 的 n 次幂的值。
 */
function pow(x, n) {
  ...
}

这种注释可以帮助我们理解函数的目的,并且不需要研究其内部的实现代码,就可以直接正确地使用它。

为什么任务以这种方式解决?
写了什么代码很重要。但是为什么 不 那样写可能对于理解正在发生什么更重要。为什么任务是通过这种方式解决的?代码并没有给出答案。

如果有很多种方法都可以解决这个问题,为什么偏偏是这一种?尤其当它不是最显而易见的那一种的时候。
ps:我认为这点是最关键的,当实现一个逻辑的时候,要写下为什么这样写。因为这次解决问题你应该基本上考虑到了所有的情况,而当下一次来review的时候如果这里没写注释,就很有可能理所当然的想到某种更加简单的解决方案,然而这种解决方案很有可能是上次就已经想到的但具有缺陷的解决方法,从而当自己意识到这个解决方案有缺陷的时候,又要重新写回之前的样子,浪费了大量的时间。

代码有哪些巧妙的特性?它们被用在了什么地方?
如果代码存在任何巧妙和不显而易见的方法,那绝对需要注释。

避免注释

  • 描述“代码如何工作”和“代码做了什么”。
  • 避免在代码已经足够简单或代码有很好的自描述性而不需要注释的情况下,还写些没必要的注释。

当然现实总不会那样的完美,例如在一些复杂的算法中,会有一些出于优化的目的而做的一些巧妙的“调整”。但是通常情况下,我们应该尽可能地保持代码的简单和“自我描述”性。

记录有感:看完注释的艺术,感觉对自身是一个极大的提升,以后还是要经常学习编程方面的艺术啊!

Last modification:July 22nd, 2021 at 03:49 pm
如果觉得我的文章对你有用,请随意赞赏