新闻资讯
如何编写高质量的 JS 函数——注释
一、有名的npm包的一些注释风格
函数注释,一方面提高了可读性,另一方面还可以生成在线文档。
一个高质量的函数,注释少不了,但是这并不代表所有的函数都需要注释。富有富的活法,穷有穷的潇洒,重要或者复杂的函数,可以写个好注释;简单或者不重要的函数,可以不写注释或者写一个简单的注释。
那么,目前函数的注释都有哪几种方式呢?
1、egg.js 的注释风格
egg.js 的入口文件的注释特点是简单整洁。
这是一个被抽象出来的基类,展示了作者 [Yiyu He] 当时写这个类的时候,其注释的风格有以下几点:
第一点:构造函数的注释规则,表达式语句的注释规则。
第二点:注释的取舍,有一些变量可以不用注释,有些要注释,不要有那种要注释就要全部注释的思想。
2、lodash.js
说到函数注释,就不能不说到 lodash.js 。由于篇幅有限,本文就不做相应介绍了,大家自行按照上面的方式去了解。
二、通过注释生成在线文档的思考
有人说注释要很规范,方便给别人,比如用 jsdoc 等 。我的观点是,对一些不需要开源的 web 项目,没有必要用 jsdoc , 理由如下:
1.繁琐,需要按照 jsdoc 规则来。
2.个人认为,jsdoc 有入侵性,文档规则需要写在代码中。
如果要写注释说明手册,对于大型项目,我推荐使用 apidoc , 因为 apidoc 入侵性不强,不要求把规则写在代码中,可以把所有规则写到一个文件中。
但是一般小项目,没有必要单独写一份 api 文档。如果是开源的大型项目,首先需要考虑是否有开源的官方网站,你会看到网上的一些开源项目官网好像很酷,其实这个世界上不缺的就是轮子,你也可以很快的做出这样的网站,
三、我个人的注释习惯
下面说说我本人对函数注释(只针对函数注释)的一些个人风格或者意见。
1、分享 VSCode 关于注释的几个工具
Better Comments 给注释上色
Document This 自动生成注释
TODO Highlight 高亮 TODO ,并可以搜寻所有 TODO
下面是一张演示图:
2、写和不写注释的平衡
我的观点是不影响可读性,复杂度低,对外界没有过度干涉的函数可以不写注释。
3、表达式语句的注释
函数内,表达式语句的注释可以简单点。如下图所示,// 后面加简要说明。
function add(a, b) { // sum .... let sum = a + b
}
4、TODO 注释
function say() { // TODO: 编写 say 具体内容 console.log('say')
}
5、FIXME 注释
function fix() { // FIXME: 删除 console.log方法 console.log('fix')
}
6、函数注释
一般分为普通函数和构造函数。
(1)普通函数注释:
/**
* add
* @param {Number} a - 数字
* @param {Number} b - 数字
* @returns {Number} result - 两个整数之和
*/ function add(a, b) { // FIXME: 这里要对 a, b 参数进行类型判断 let result = a + b return (result)
}
(2)构造函数注释:
class Kun { /**
* @constructor
* @param {Object} opt - 配置对象
*/ constructor(opt = {}) { // 语句注释 this.config = opt
}
}
7、总结
从开源项目的代码中可以发现,在遵守注释的基本原则的基础上,注释的风格多种多样;同一个作者不同项目的注释风格也有所差别,但我会尽可能的去平衡注释和不注释。
回复列表