-
注释的目的：
提高代码的可读性，从而提高代码的可维护性 -
注释的原则：
如无必要，勿增注释 ( As short as possible )
如有必要，尽量详尽 ( As long as necessary )
一般用于简单的描述，如某些状态描述、属性描述等。注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行。
- 推荐：
...
- 不推荐
2 、模块注释......
一般用于描述模块的名称以及模块开始与结束的位置。
注释内容前后各一个空格字符， 表示模块开始， 表示模块结束，模块与模块之间相隔一行。
- 推荐：
......
- 不推荐
3、嵌套模块注释......
当模块注释内再出现模块注释的时候，为了突出主要模块，嵌套模块不再使用。
而改用
注释写在模块结尾标签底部，单独一行。
二、CSS 文件注释 1、单行注释......
注释内容第一个字符和最后一个字符都是一个空格字符，单独占一行，行与行之间相隔一行。
- 推荐：
.jda {}
.jdb {}
- 不推荐：
.jdc {
display: block;
}
.jdc {
display: block;
}
2、模块注释
注释内容第一个字符和最后一个字符都是一个空格字符， 占一行，行与行之间相隔两行。
- 推荐：
.mod_a {}
.mod_b {}
- 不推荐：
.mod_a {}
.mod_b {}
3、文件注释
在样式文件编码声明 @charset 语句下面注明页面名称、作者、创建日期等信息。
@charset "UTF-8";三、JavaScript 文件注释 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
}
2、多行注释
多行注释使用 ，而不是多行的 //。
- 推荐：
function make (tag) {
// ...
return element
}
- 不推荐：
// make() returns a new element
// based on the passed in tag name
function make (tag) {
// ...
return element
}
3、注释空格
注释内容和注释符之间需要有一个空格，以增加可读性。eslint: spaced-comment。
- 推荐
// is current tab
const active = true
function make(tag) {
// ...
return element
}
- 不推荐：
//is current tab
const active = true
function make(tag) {
// ...
return element
}
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
}
}
5、文档类注释
文档类注释，如函数、类、文件、事件等；都使用 jsdoc 规范。
function Book (title, author) {
this.title = title
this.author = author
}
Book.prototype = {
getTitle: function () {
return this.title
},
setPageNum: function (pageNum) {
this.pageNum=pageNum
}
}
6、注释工具
ESLint是当下最流行的 JS 代码检查工具，ESLint中有一些注释相关的规则，用户可选择开启：
- valid-jsdoc
- require-jsdoc
- no-warning-comments
- capitalized-comments
- line-comment-position
- lines-around-comment
- multiline-comment-style
- no-inline-comments
- spaced-comment
- 缩进换行请使用两个空格。
- 大型团队多人协作项目推荐 JavaScript 代码末尾加分号。
- 小型个人创新练手项目可尝试使用 JavaScript 代码末尾不加分号的风格，更加清爽简练。
