🌟三、注释规范
注释的目的：
- 提高代码的可读性，从而提高代码的可维护性 注释的原则：
- 如无必要，勿增注释 ( As short as possible ) ；
- 如有必要，尽量详尽 ( As long as necessary )。
3.1 HTML 文件注释
3.1.1 单行注释
一般用于简单的描述，如某些状态描述、属性描述等。
注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行。
- 推荐：
<!-- Comment Text --> <div>...</div>
复制代码
- 不推荐
<div>...</div><!-- Comment Text --> <div><!-- Comment Text --> ... </div>
3.1.2 模块注释
一般用于描述模块的名称以及模块开始与结束的位置。
注释内容前后各一个空格字符， 表示模块开始， 表示模块结束，模块与模块之间相隔一行。
- 推荐：
<!-- S Comment Text A --> <div class="mod_a"> ... </div> <!-- E Comment Text A --> <!-- S Comment Text B --> <div class="mod_b"> ... </div> <!-- E Comment Text B -->
- 不推荐
<!-- S Comment Text A --> <div class="mod_a"> ... </div> <!-- E Comment Text A --> <!-- S Comment Text B --> <div class="mod_b"> ... </div> <!-- E Comment Text B -->
3.1.3 嵌套模块注释
当模块注释内再出现模块注释的时候，为了突出主要模块，嵌套模块不再使用。
<!-- S Comment Text --> <!-- E Comment Text -->
而改用
<!-- /Comment Text -->
注释写在模块结尾标签底部，单独一行。
<!-- S Comment Text A --> <div class="mod_a"> <div class="mod_b"> ... </div> <!-- /mod_b --> <div class="mod_c"> ... </div> <!-- /mod_c --> </div> <!-- E Comment Text A -->
3.2 CSS 文件注释
3.2.1 单行注释
注释内容第一个字符和最后一个字符都是一个空格字符，单独占一行，行与行之间相隔一行。
- 推荐：
/* Comment Text */ .jdc {} /* Comment Text */ .jdc {}
- 不推荐：
/*Comment Text*/ .jdc { display: block; } .jdc { display: block;/*Comment Text*/ }
3.2.2 模块注释
注释内容第一个字符和最后一个字符都是一个空格字符，/ 与 模块信息描述占一行，多个横线分隔符 - 与 / 占一行，行与行之间相隔两行。
- 推荐：
/* Module A ---------------------------------------------------------------- */ .mod_a {} /* Module B ---------------------------------------------------------------- */ .mod_b {}
- 不推荐：
/* Module A ---------------------------------------------------- */ .mod_a {} /* Module B ---------------------------------------------------- */ .mod_b {}
3.2.3 文件注释
在样式文件编码声明
@charset语句下面注明页面名称、作者、创建日期等信息。
@charset "UTF-8"; /** * @desc File Info * @author Author Name * @date 2015-10-10 */
3.3 JavaScript 文件注释
3.3.1 单行注释
单行注释使用 //，注释应单独一行写在被注释对象的上方，不要追加在某条语句的后面.
- 推荐：
// is current tab const active = true
- 不推荐：
const active = true // is current tab
注释行的上方需要有一个空行（除非注释行上方是一个块的顶部），以增加可读性。
- 推荐：
function getType () { console.log('fetching type...') // set the default type to 'no type' const type = this.type || 'no type' return type }
// 注释行上面是一个块的顶部时不需要空行 function getType () { // set the default type to 'no type' const type = this.type || 'no type' return type }
不推荐
function getType () { console.log('fetching type...') // set the default type to 'no type' const type = this.type || 'no type' return type }
3.3.2 多行注释
多行注释使用 / … /，而不是多行的 //。*
- 推荐：
/** * make() returns a new element * based on the passed-in tag name */ function make (tag) { // ... return element }
不推荐
// make() returns a new element // based on the passed in tag name function make (tag) { // ... return element }
3.3.3 注释空格
注释内容和注释符之间需要有一个空格，以增加可读性。
eslint: spaced-comment。
- 推荐：
// is current tab const active = true /** * make() returns a new element * based on the passed-in tag name */ function make(tag) { // ... return element }
不推荐：
//is current tab const active = true /** *make() returns a new element *based on the passed-in tag name */ function make(tag) { // ... return element }
3.3.4 特殊标记
有时我们发现某个可能的 bug，但因为一些原因还没法修复；或者某个地方还有一些待完成的功能，这时我们需要使用相应的特殊标记注释来告知未来的自己或合作者。常用的特殊标记有两种：
// FIXME: 说明问题是什么/ TODO: 说明还要做什么或者问题的解决方案
class Calculator extends Abacus { constructor () { super () // FIXME: shouldn’t use a global here total = 0 // TODO: total should be configurable by an options param this.total = 0 } }
3.3.5 文档类注释
文档类注释，如函数、类、文件、事件等；都使用 jsdoc 规范。
/** * Book类，代表一个书本. * @constructor * @param {string} title - 书本的标题. * @param {string} author - 书本的作者. */ function Book (title, author) { this.title = title this.author = author } Book.prototype = { /** * 获取书本的标题 * @returns {string|*} */ getTitle: function () { return this.title }, /** * 设置书本的页数 * @param pageNum {number} 页数 */ setPageNum: function (pageNum) { this.pageNum=pageNum } }
3.3.6 注释工具
ESLint是当下最流行的 JS 代码检查工具，ESLint中有一些注释相关的规则，用户可选择开启：
valid-jsdocrequire-jsdocno-warning-commentscapitalized-commentsline-comment-positionlines-around-commentmultiline-comment-styleno-inline-comments
spaced-comment
🌟写在最后
以上就是今天文章的全部内容啦！有一个养成编程代码规范，对今后开发以及协同开发等都有很大的好处；大家一定要重视起来哦。各位小伙伴让我们 let’s be prepared at all times！
