一、有名的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、总结

从开源项目的代码中可以发现，在遵守注释的基本原则的基础上，注释的风格多种多样；同一个作者不同项目的注释风格也有所差别，但我会尽可能的去平衡注释和不注释。