前端代码规范 |
您所在的位置：网站首页 › HTML5注释符号 › 前端代码规范 |
|
注释规范 注释的目的： 提高代码的可读性，从而提高代码的可维护性注释的原则： 如无必要，勿增注释 ( As short as possible )如有必要，尽量详尽 ( As long as necessary )HTML 文件注释单行注释一般用于简单的描述，如某些状态描述、属性描述等。 注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行。 推荐： ...不推荐：... ... 模块注释一般用于描述模块的名称以及模块开始与结束的位置。 注释内容前后各一个空格字符， 表示模块开始， 表示模块结束，模块与模块之间相隔一行。 推荐： ... ... 不推荐： ... ... 嵌套模块注释当模块注释内再出现模块注释的时候，为了突出主要模块，嵌套模块不再使用。 而改用 注释写在模块结尾标签底部，单独一行。 ... ... CSS 文件注释单行注释注释内容第一个字符和最后一个字符都是一个空格字符，单独占一行，行与行之间相隔一行。 推荐：/* Comment Text */ .jdc {} /* Comment Text */ .jdc {}不推荐：/*Comment Text*/ .jdc { display: block; } .jdc { display: block;/*Comment Text*/ }模块注释注释内容第一个字符和最后一个字符都是一个空格字符，/* 与 模块信息描述占一行，多个横线分隔符 - 与 */ 占一行，行与行之间相隔两行。 推荐：/* Module A ---------------------------------------------------------------- */ .mod_a {} /* Module B ---------------------------------------------------------------- */ .mod_b {}不推荐：/* Module A ---------------------------------------------------- */ .mod_a {} /* Module B ---------------------------------------------------- */ .mod_b {}文件注释在样式文件编码声明 @charset 语句下面注明页面名称、作者、创建日期等信息。 @charset "UTF-8"; /** * @desc File Info * @author Author Name * @date 2015-10-10 */JavaScript 文件注释单行注释单行注释使用 //，注释应单独一行写在被注释对象的上方，不要追加在某条语句的后面。 推荐：// 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 }多行注释多行注释使用 /** ... */，而不是多行的 //。 推荐：/** * 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 }注释空格注释内容和注释符之间需要有一个空格，以增加可读性。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 }特殊标记有时我们发现某个可能的 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 } }文档类注释文档类注释，如函数、类、文件、事件等；都使用 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 } }注释工具ESLint 是当下最流行的 JS 代码检查工具，ESLint 中有一些注释相关的规则，用户可选择开启： valid-jsdocrequire-jsdocno-warning-commentscapitalized-commentsline-comment-positionlines-around-commentmultiline-comment-styleno-inline-commentsspaced-comment |
今日新闻 |
推荐新闻 |
| CopyRight 2018-2019 办公设备维修网 版权所有 豫ICP备15022753号-3 |