编写高质量可维护的代码：一目了然的注释

时间  2021-08-14
标签 javascript css html 前端 java python linux git github 编程 栏目 JavaScript 繁體版
原文   原文链接

这是第 71 篇不掺水的原创，想获取更多原创好文，请搜索公众号关注咱们吧~ 本文首发于政采云前端博客：编写高质量可维护的代码：一目了然的注释javascript

前言

有一些人认为，好的代码是自我解释的。合适的命名和优秀的代码的确能够减轻开发人员阅读代码的工做量，对于不是特别复杂的代码可能确实能够作到自我解释。但并非全部场景均可以作到这一点，咱们一块儿来了解一下“注释”吧。css

编程语言中对“注释”的解释

注释就是对代码的解释和说明。注释是开发人员在编写程序时，给一段代码的解释或提示，有助于提升程序代码的可读性。注释不会被计算机编译。html

要不要加注释？为何要加注释？

注释的存在就是为了方便本身的二次阅读和代码维护以及项目交接。能够更好的理解代码，有助于提升协做效率，加快开发进程。前端

试想，你添加了一段逻辑较为复杂的代码，几个月后再看，还能不能迅速看懂？你刚刚接手一个老项目，项目里基本没有注释且逻辑复杂，你能高效率的看懂代码和了解业务吗？java

因此添加注释仍是有必定必要滴。python

基础篇

快捷键 windows： ctrl+/ mac： command+/linux

注释的分类

1、 HTML 中的注释git

<div>
      这是一行文字
      <!-- 这是一行被注释的文字 -->
</div>
复制代码

2、CSS 中的注释github

  • 在 .html 文件中
<style> div { /* color: #fff; */ } </style>
复制代码
  • 在 .css 文件中
div {
	/* color: #fff; */
}
复制代码
  • 在 .less 或 .scss 文件中
div {
	/* color: #fff;*/  /* 多行注释*/
	// font-size: 14px; // 单行注释
	background: #000;
}
复制代码

3、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;
};
复制代码

4、特殊标记注释

  • **TODO **在该注释处有功能代码待编写，待实现的功能在说明中会简略说明
  • FIXME 在该注释处代码须要修正，甚至代码是错误的，不能工做，须要修复，如何修正会在说明中简略说明
  • **XXX **在该注释处代码虽然实现了功能，可是实现的方法有待商榷，但愿未来能改进，要改进的地方会在说明中简略说明
  • **NOTE **在该注释处说明代码如何工做
  • **HACK **在该注释处编写得很差或格式错误，须要根据本身的需求去调整程序代码
  • **BUG **在该注释处有 Bug
// TODO功能未完成，待完善
// FIXME 待修复
// XXX 实现方法待确认
// NOTE 代码功能说明
// HACK 此处写法有待优化
// BUG 此处有 Bug
const arr = []
复制代码

Tips：

  • 为何 // 注释能够在 .less 或 .scss 文件中使用，可是在 .html 和 .css 文件中不生效？
    • 在 MDN 中关于 CSS 注释只有 /* */ 一种语法。可是在 LESS 和 SCSS 中支持注释的语法和 JS 中保持一致，有单行注释 // 和多行注释 /* */ 两种。单行注释编译以后不会被保留。
  • 单行注释为何有时候写在代码上方，有时候写在代码后方？
    • 注释能够书写在代码中的任意位置。我的理解，通常写在代码上方的时候意为对后面一段代码的注释，而写在代码后方的时候意为对本行代码的注释。

注释写法规范

  • 文件注释
    • 位于文件头部，通常包含概要、做者、版本改动信息以及修改时间等内容
/* * 简述当前文件功能 * @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) {}
复制代码

了解更多可查看 JSDoc

拓展篇

IE 条件注释（IE5+）

IE 条件注释分为如下几种状况：

  • 只容许 IE 解释执行 <!--[if IE]><![endif]-->
  • 只容许 IE 特定版本解释执行 <!--[if IE 7]><![endif]-->
  • 只容许非 IE 特定版本执行注释 <!--[if !IE 7]><![endif]-->
  • 只容许高于或低于 IE 特定版本执行注释 <!--[if gt IE 7]><![endif]-->
<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>
复制代码

# （井号）注释 和 ''' （三引号）注释

  • # 通常出如今各类脚本配置文件中，用法与 JS 单行注释 // 基本相同。Python 中也经常用到
  • ''' 是 Python 中的多行注释语法，用两个 ''' 包含被注释的段落
# python 的单行注释一
	print("I could have code like this.") # python 的单行注释二

# print("This won't run.") # 被注释的代码

''' 被三引号包裹的段落 能够随意折行 也能够注释代码 print("This won't run.") '''
复制代码

注释 “被执行” 了？

众所周知，注释的代码是不会被执行的。可是小编在查资料时看到了一段比较有意思的代码， Java 中的一行注释“被执行”了？

public class Test {
	public static void main(String[] args) {
		String name = "赵大";
		// \u000dname="钱二";
		System.out.println(name);
	}
}
复制代码

这段代码执行后的结果为钱二，也就是说在这段代码中，“被注释”的那行代码生效了！

这段代码的问题出在 \u000d 这串特殊字符上。\u000d 是一串 Unicode 字符，表明换行符。Java 编译器不只会编译代码，还会解析 Unicode 字符。在上面这段代码把 \u000d 给解析了，后面的代码就到了下面一行，超出了被注释的范围（单行注释的注释范围仅在当前行），因此执行结果为 钱二 而非 赵大。（以下）

public class Test {
	public static void main(String[] args) {
		String name = "赵大";
		//
		name="钱二";
		System.out.println(name);
	}
}
复制代码

因此本质上在代码执行的时候 name="钱二" 并无被注释，而是被换了行（奇怪的知识增长了）。 因此切记，注释确实是不会被执行的哦！

注释相关插件

在这里推荐几个我的认为比较好用的注释相关的 Vscode 插件，可在 setting.json 文件下自定义设置（可经过 '文件—首选项—设置'，打开 Vscode 文件 settings.json ）

  • koroFileHeader 在vscode中用于生成文件头部注释和函数注释的插件
  • 文件头部添加注释
    • 在文件开头添加注释，记录文件信息/文件的传参/出参等
    • 支持用户高度自定义注释选项, 适配各类需求和注释。
    • 保存文件的时候，自动更新最后的编辑时间和编辑人
    • 快捷键：window：ctrl+alt+i，mac：ctrl+cmd+i，linux：ctrl+meta+i

  • 在光标处添加函数注释
    • 在光标处自动生成一个注释模板
    • 支持用户高度自定义注释选项
    • 快捷键：window：ctrl+alt+t，mac：ctrl+cmd+t，linux：ctrl+meta+t
    • 快捷键不可用极可能是被占用了，参考这里
    • 可自定义默认参数

  • Better Comments 经过使用警报，信息，TODO 等进行注释来改善代码注释。使用此扩展，您将可以将注释分类为：
    • 快讯
    • 查询
    • 待办事项
    • 强调
    • 注释掉的代码也能够设置样式，以使代码不该该存在
    • 可自定义指定其余所需的注释样式

  • TODO Highlight 突出显示TODO，FIXME和任何关键字
    • 高亮内置关键字，可经过自定义设置覆盖外观
    • 也可自定义关键字

用事实说话

口说无凭，眼见为实。下面咱们看下实际开发中的具体状况：

  • 没有注释
const noWarehousetemIds = beSelectSkucontainer.reduce((arr, itemId) => {
    const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
      const sku = selectRowskey[itemId][skuId];
      return !!sku.warehouseCode || lodashGet(warehouses, '[0].code');
    });
    if (!res) {
      arr.push(itemId);
    }
    return arr;
  }, []);
  if (noWarehousetemIds.length > 0 || noStockItemIds.length > 0) {
    const itemIds = Array.from(new Set([...noWarehousetemIds, ...noStockItemIds]));
    const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
    return Modal.warning({
      title: '错误提示',
      content: `“${itemNames.join(',')}”库存信息未完善，请完善库存信息`,
    });
  }
复制代码
  • 通常般的注释
// 遍历当前全部选中的sku，查找出没有库存的itemId
const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
  const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
    const sku = selectRowskey[itemId][skuId];
    return !!sku.stockQuantity;
  });
  if (!res) {
    arr.push(itemId);
  }
  return arr;
}, []);
// 有一条sku的库存为空时进入校验
if (noStockItemIds.length > 0) {
  const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
  return Modal.warning({
    title: '错误提示',
    content: `“${itemNames.join(',')}”库存信息未完善，请完善库存信息`,
  });
}
复制代码
  • 更好的注释
// 遍历当前全部选中的sku，查找出没有库存的itemId
const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
    // selectRowskey是一个对象，以itemId为key，sku对象做为value，sku对象以skuId做为key，sku做为value，只有selectRowskey下全部itemId下的sku都有库存才算校验经过
    /*         数据格式:         selectRowskey: {           12345678: { // itemId               123456: { // skuId               name: 'sku',               }           }         }       */
    const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
        const sku = selectRowskey[itemId][skuId];
        return !!sku.stockQuantity;
    });
    // 只要有一条sku没有库存时，就塞到arr中，返回给noStockItemIds数组
    if (!res) {
        arr.push(itemId);
    }
    return arr;
}, []);
// 有一条sku的库存为空时进入校验
if (noStockItemIds.length > 0) {
    // 根据id查找商品名称
    const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
    Modal.warning({
        title: '错误提示',
        content: `“${itemNames.join(',')}”库存信息未完善，请完善库存信息`,
    });
}
复制代码

看到上面这段代码能够很明显的体会到有没有注释以及注释写的清不清楚的重要性。如果写了注释但仍然看不懂，那还不如不写。

因此注释也不是随便写一写就能够的，要描述某段代码的功能，注明逻辑，让开发者能够”无脑“浏览。

以前在工做群中看到有人发过这样一张图（以下图），我的认为是一个很好的代码注释的范例：

结语

看到这里，对于注释的重要性各位已经有本身的认知。还有几点是咱们写注释时须要注意的：

  • 注释内容要简洁、清楚明了。注释简述功能或实现逻辑便可，无需每行代码都添加注释

  • 代码如有修改，切记同步修改对应的注释。不要出现过时的注释，不然会起到副作用

    有任何意见欢迎下方评论区留言讨论~

参考文献

为何要写注释 js/javascript代码注释规范与示例 代码中的特殊注解 -- TODO、FIXME、XXX的做用 注释的做用, 以及如何写注释 你肯定Java注释不会被执行吗？80%的人都不知道。 IE 浏览器条件注释详解 关于CSS中对IE条件注释的问题

推荐阅读

个人前端职业进阶之路

浅谈 React 中的 XSS 攻击

招贤纳士

政采云前端团队（ZooTeam），一个年轻富有激情和创造力的前端团队，隶属于政采云产品研发部，Base 在风景如画的杭州。团队现有 40 余个前端小伙伴，平均年龄 27 岁，近 3 成是全栈工程师，妥妥的青年风暴团。成员构成既有来自于阿里、网易的“老”兵，也有浙大、中科大、杭电等校的应届新人。团队在平常的业务对接以外，还在物料体系、工程平台、搭建平台、性能体验、云端应用、数据分析及可视化等方向进行技术探索和实战，推进并落地了一系列的内部技术产品，持续探索前端技术体系的新边界。

若是你想改变一直被事折腾，但愿开始能折腾事；若是你想改变一直被告诫须要多些想法，却无从破局；若是你想改变你有能力去作成那个结果，却不须要你；若是你想改变你想作成的事须要一个团队去支撑，但没你带人的位置；若是你想改变既定的节奏，将会是“5 年工做时间 3 年工做经验”；若是你想改变原本悟性不错，但老是有那一层窗户纸的模糊… 若是你相信相信的力量，相信平凡人能成就非凡事，相信能遇到更好的本身。若是你但愿参与到随着业务腾飞的过程，亲手推进一个有着深刻的业务理解、完善的技术体系、技术创造价值、影响力外溢的前端团队的成长历程，我以为咱们该聊聊。任什么时候间，等着你写点什么，发给 ZooTeam@cai-inc.com

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程