玩转代码|分享一些实用的Vue 前端代码（三）

目录

三、注释规范

3.1 HTML 文件注释

3.1.1 单行注释

3.1.2 模块注释

3.1.3 嵌套模块注释

3.2 CSS 文件注释

3.2.1 单行注释

3.2.2 模块注释

3.2.3 文件注释

3.3 JavaScript 文件注释

3.3.1 单行注释

3.3.2 多行注释

3.3.3 注释空格

3.3.4 特殊标记

3.3.5 文档类注释

3.3.6 注释工具

---

三、注释规范

注释的目的：

• 提高代码的可读性，从而提高代码的可维护性

注释的原则：

• 如无必要，勿增注释 ( As short as possible )
• 如有必要，尽量详尽 ( As long as necessary )

3.1 HTML 文件注释

3.1.1 单行注释

一般用于简单的描述，如某些状态描述、属性描述等。

注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行。

• 推荐：

• <div>...div>
  

• 不推荐

  <div>...div>
   
  <div>
    ...
  div>
  

3.1.2 模块注释

一般用于描述模块的名称以及模块开始与结束的位置。

注释内容前后各一个空格字符， 表示模块开始， 表示模块结束，模块与模块之间相隔一行。

• 推荐：

  	
  <div class="mod_a">
    ...
  div>
  	
  	
  <div class="mod_b">
    ...
  div>
  

• 不推荐

<div class="mod_a">
  ...
div>
	
<div class="mod_b">
  ...
div>

3.1.3 嵌套模块注释

当模块注释内再出现模块注释的时候，为了突出主要模块，嵌套模块不再使用。

而改用

注释写在模块结尾标签底部，单独一行。

<div class="mod_a">
		
    <div class="mod_b">
        ...
    div>
    
    	
    <div class="mod_c">
    	...
    div>
    
		
div>

 

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-jsdoc
• require-jsdoc
• no-warning-comments
• capitalized-comments
• line-comment-position
• lines-around-comment
• multiline-comment-style
• no-inline-comments
• spaced-comment