可以通过设置编辑器来设置出一致的注释模式。
1. HTML注释
- 模块注释
<!-- 订单详情模块 -->
- 区块注释
<!--
@name: 订单详情
@description: 主要是订单详情页面
@author: fjw(fjw@gmail.com)
-->
2. CSS注释
- 组件块和子组件块以及声明块之间使用一空行分隔,子组件块之间三空行分隔;
/* ==========================================================================
组件块
============================================================================ */
/* 子组件块
============================================================================ */
.selector {
padding: 15px;
margin-bottom: 15px;
}
/* 子组件块
============================================================================ */
.selector-secondary {
display: block; /* 注释*/
}
.selector-three {
display: span;
}
3. JavaScript注释
-
单行注释:
独占一行,后跟一个空格,缩进与下一行被注释说明的代码一致。 -
多行注释:
避免使用 /.../ 这样的多行注释。有多行注释内容时,使用多个单行注释。 -
函数/方法注释:
- 必须包含函数的说明;
- 有参数和返回值时,必须有注释标志;
- 参数和返回值必须包含类型信息和说明;
- 当函数是内部函数,外部不可以访问时,可以使用@inner来标识;
- 示范:
/** * 函数描述 * * @param {string} p1 参数1的说明 * @param {string} p2 参数2的说明 * @param {number=} p3 参数3的说明(可选) * @return {Object} 返回值描述 */ function foo(p1, p2, p3) { var p3 = p3 || 10; return { p1: p1, p2: p2, p3: p3 }; }
4. 文件注释
- 文件注释用于告诉不熟悉这段代码的读者这个文件中包含哪些东西。
- 文件注释要标明作者、文件版本、创建/修改时间、重大版本修改记录;
- 示范:
/** * @fileoverview Description of file, its uses and information * about its dependencies. * @author user@qq.com (Firstname Lastname) * Copyright 2019 QQ Inc. All Rights Reserved. */
!!! 以上规则仅供参考
网友评论