编写高质量的代码注释
2023-02-21 周二
注释简介
注释就是对代码的解释和说明。注释是开发人员在编写程序时，给一段代码的解释或提示，有助于提高程序代码的可读性。注释不会被计算机编译。
要不要加注释？为什么要加注释？
注释的存在就是为了方便自己的二次阅读和代码维护以及项目交接。可以更好的理解代码，有助于提高协作效率，加快开发进程。
试想，你添加了一段逻辑较为复杂的代码，几个月后再看，还能不能迅速看懂？你刚刚接手一个老项目，项目里基本没有注释且逻辑复杂，你能高效率的看懂代码和了解业务吗？
所以添加注释还是有一定必要的。
快捷键
快捷键 windows： ctrl+/ mac： command+/
不同文件中的注释类型
在HTML中
<div>
这是一行文字
<!-- 这是一行被注释的文字 -->
</div>
在CSS中
在.html文件中
<style>
div {
/* color: #fff; */
}
</style>
在.css文件中
div {
/* color: #fff; */
}
在.less或者.scss中
div {
/* color: #fff;*/ /* 多行注释*/
// font-size: 14px; // 单行注释
background: #000;
}
在JS中
- 用法
- 可用于解释 JavaScript 代码，增强其可读性。
- 也可以用于阻止代码执行。
单行注释（行注释）
以 // 开头。任何位于 // 之后的文本都会被注释
// 定义一个空数组
var ary = [];
var ary2 = []; // 又定义一个空数组
多行注释（块注释）
以 /* 开头，以 / 结尾。任何位于 / 和 */ 之间的文本都会被注释
/*
这是多行注释
定义一个数组
*/
var ary = [];
用注释来阻止代码执行
被注释的 JS 代码将不被执行
//alert("123") // 执行时未弹出该信息
alert("456") // 执行时弹出该信息
函数注释
一般以 /** 开头，以 / 结尾。任何位于 /* 和 */ 之间的文本都会被注释
/**
* 提交
*
* @method onSubmit
* @param {[Object]} 提交数据
* @return {[Bollean]} [返回是否提交成功 ]
*/
const onSubmit = (params = {}) => {
const result = false;
if (params) {
result = true;
}
return result;
};
特殊标记注释
TODO在该注释处有功能代码待编写，待实现的功能在说明中会简略说明
FIXME 在该注释处代码需要修正，甚至代码是错误的，不能工作，需要修复，如何修正会在说明中简略说明
XXX在该注释处代码虽然实现了功能，但是实现的方法有待商榷，希望将来能改进，要改进的地方会在说明中简略说明
NOTE在该注释处说明代码如何工作
HACK在该注释处编写得不好或格式错误，需要根据自己的需求去调整程序代码
BUG在该注释处有 Bug
// TODO功能未完成，待完善
// FIXME 待修复
// XXX 实现方法待确认
// NOTE 代码功能说明
// HACK 此处写法有待优化
// BUG 此处有 Bug
const arr = []
注释写法规范
文件注释
位于文件头部，一般包含概要、作者、版本改动信息以及修改时间等内容
/*
* 简述当前文件功能
* @author 作者名称
* @version 版本号 最近编辑时间
* @description 该版本改动信息
*/
单行注释
总是在 // 后留一个空格
// 这是一行注释
多行注释
总是保持星号纵向对齐（结束符前留一个空格）
不要在开始符、结束符所在行写注释
尽量使用单行注释代替多行注释
注释函数时，推荐使用多行注释
/*
这里有一行注释
这里有一行注释
这里有一行注释
*/
函数注释
其间每一行都以 * 开头，且与第一行第一个 * 对齐
注释内容与 * 间留一个空格
必须包含标签注释。例：
/**
* 方法说明
* @method 方法名
* @for 所属类名
* @param {参数类型} 参数名 参数说明
* @return {返回值类型} 返回值说明
*/
注释常用标签用法
@type {typeName}
- 表示任何类型
? 表示可以为 null
! 表示不能为 null
[] 表示数组
/**
* @type {number}
*/
var foo1;
/**
* @type {*}
* @desc 任何类型
*/
var foo2;
/**
* @type {?string}
* @desc string或者null
*/
var foo3;
@param {} name - some description
非必传参数需给参数名加上 []
参数如有默认值需用 = 表示
如果参数是 Object，可继续用 @param 对其属性进行详细说明
若干个参数用 ... 表示
/**
* @func
* @desc 一个带参数的函数
* @param {string} a - 参数a
* @param {number} b=1 - 参数b默认值为1
* @param {string} c=1 - 参数c有两种支持的取值 1—表示x 2—表示xx
* @param {object} d - 参数d为一个对象
* @param {string} d.e - 参数d的e属性
* @param {object[]} g - 参数g为一个对象数组
* @param {string} g.h - 参数g数组中一项的h属性
* @param {string} [j] - 参数j是一个可选参数
*/
function foo(a, b, c, d, g, j) {}
/**
* @func
* @desc 一个带若干参数的函数
* @param {...string} a - 参数a
*/
function bar(a) {}
IE条件注释（IE5+）
IE 条件注释分为以下几种情况：
只允许 IE 解释执行
只允许 IE 特定版本解释执行
只允许非 IE 特定版本执行注释
只允许高于或低于 IE 特定版本执行注释
<head>
<title>IE 条件注释</title>
<!-- 是 IE 时 -->
<!--[if IE]>
<link href="style.css" rel="stylesheet" type="text/css" />
<![endif]-->
<!-- 是 IE 7 时 -->
<!--[if IE 7]>
<link href="style.css" rel="stylesheet" type="text/css" />
<![endif]-->
<!-- 不是 IE 7 时 -->
<!--[if !IE 7]>
<link href="style.css" rel="stylesheet" type="text/css" />
<![endif]-->
<!-- 大于 IE 7 时 -->
<!--[if gt IE 7]>
<link href="style.css" rel="stylesheet" type="text/css" />
<![endif]-->
<!-- 小于 IE 7 时 -->
<!--[if lt IE 7]>
<link href="style.css" rel="stylesheet" type="text/css" />
<![endif]-->
</head>
作者：政采云前端团队
原文链接
感觉这篇文章特别实用，mark一下。
