代码整洁之道－如何写好注释
写在前面
程序员都不喜欢写注释，但是都希望别人的代码写注释!
这句话听起来是一段梗，不过，代码注释的确需要我们重视，或许在某个夜晚，你正在加班紧急修改线上BUG，一行及时有用的注释让你如沐春风，直呼痛快!
总结
尽量少写注释，让自己的代码有足够的表达力，恰当的注释是应该只是一种弥补，弥补我们代码无法快速表达意图的情况
但是， But，并不是不写注释的理由
对于晦涩难懂的代码逻辑，特殊情况的业务逻辑，等，应当简洁明了，而非拖泥带水的给出解释注释。
摘抄
- 带有少量注释的整洁而有表达力的代码，比带有大量零碎注释的复杂代码好的多
- 别给糟糕的代码加注释–重新写吧！
- 什么也比不上放置良好的注释来的有用
- 什么也比不上乱七八槽的注释更有本事搞乱一个模块
- 什么也不会比陈旧，提供错误信息的注释更有破坏性
- 注释并不像辛德勒的名单一样“纯然的好”
怎么样写好注释
1.1 提供信息的注释
Bad
// 返回一个商品的实例
function responderInstance() {}
这时就可以去掉这一段的注释
为函数取一个好的有表达力的名字
Good
function responderGoodsInstance() {}
这个注释就非常有必要
// 匹配邮箱的正则表达式let reg = /[\w]+(\.[\w]+)*@[\w]+(\.[\w])+/
理解起来有点苦难的地方，可以加一些阐述
// 假设是第三方库我们无法修改
function compare(a, b) {if (a > b) return 1if (a === b) return 0if (a < b) return -1
}compare(a, b) !== 0 // a !== b
compare(a, b) === -1 // a < b
compare(a, b) > -1 // a >= b
compare(a, b) === 1 // a > b
...
1.2 对意图的解释
带有少量注释的整洁而有表达力的代码，比带有大量零碎注释的复杂代码好的多
可以使用多行注释，解释清楚这一部分逻辑处理的原因
我自己比较喜欢这样的注释，对于实在不好理解的逻辑，在函数上方把这个函数做的事情描述清楚
Good
function componentWillMount() {let _params = this.$router.paramsthis.params = resolveParams(params)
}/*
* 用于url在某些情况下会被转义
* 所以把路由的每一个参数都经过一遍转义字符的处理 防止异常情况
*/
function resolveParams(params) {params = params || {}for (let _key in _params) {let key = _key.replace(/amp;/g, '')params[key] = _params[_key]}return params
}
Bad
这样的注释就符合了不好注释：大量零碎注释的复杂代码
function resolveParams(params) {params = params || {}// 遍历路由参数for (let _key in _params) {// 把转义字符替换为空字符串let key = _key.replace(/amp;/g, '')params[key] = _params[_key]}return params
}
1.3 放大
用来放大某种看似不合理的地方，但是又很重要的地方
function main() {/** 这一步看似无厘头，但是很重要，请不要删除 */
}
坏注释
2.1 零碎的注释
应该在函数头部把函数意图描述清楚，别人懂了意图之后可以很快速的看懂代码
你要相信，看你代码的人肯定也是高手
function resolveParams(params) {params = params || {}// 遍历路由参数for (let _key in _params) {// 把转义字符替换为空字符串let key = _key.replace(/amp;/g, '')params[key] = _params[_key]}return params
}
2.2 多余的注释
class Goods {constructor(name, prize) {// 商品名this.name = name// 商品价格this.prize = prize}}
2.3 位置标记
function main(){// start=================do something// end=================
}
2.4 日志记录
完全可以用git commit记录好
function main(){/*** 2021.4.3 修改了xxx的逻辑* 2022.6.3 增加了xxx的逻辑*/do something
}
2.5 注释掉的代码
删除掉注释的代码，commit写好，在git中都可以找到历史记录