注释-可维护的Javascript 编写指南

可维护的Javascript 编写指南-注释                     

回到目录

目标：简洁，易读，轻量

症状：注释不到位，不准确，过多，过少，都会透支开发人员维护的耐心，和无谓的汗水。

背景：在项目开发中，注释比较糟糕的情况比较多，注释的作用多半突显在维护阶段，扩展阶段。要么每个功能，甚至每块代码都有注释，反之，也有人说，项目太赶了，没空写注释。直到项目结束，想一想下个项目就要开始了，干脆就算了。

有两种常用的注释，单行注释，多行注释。

单行注释

• 单行注释通常放在代码上面的一行，注释上面要用空行隔开。单行注释应该和代码保持相同的缩进。
• 当单行注释被放在代码所在行的后面时，至少保持一个Tab缩进。如果注释过长，就需要把注释放在代码的上一行。
• 如果注释内容不只一行内容，请用多行注释

// 推荐
if(条件){

  // 如果你要注释，内容在这里写
  operate();  
}

// 错误 中间没空一行
if(条件){
  // 如果你要注释，内容在这里写
  operate();  
}


// 错误  缩进不一致
if(条件){

// 如果你要注释，内容在这里写
  operate();  
}

// 推荐
var totalSum=sum+addSum;    // addSum为添加的数量

// 错误 注释和代码之间没有缩进
var totalSum=sum+addSum;// addSum为添加的数量

// 错误 这里应该是多行注释
// 这段代码主要判断isSelected为真时，页面元素显示为disabled,
// 否则应该显示可以选择
if(isSelected){

   // 对页面元素执行事件
   changeColor();
}    

多行注释

多行注释，格式：/*内容*/，如下都是有效的

/*此处为示例注释*/

/*又一条示例
注释*/

/*
再一条示例
注释
*/

虽然以上都有效，但是不推荐这样做。注释可以参考java的多行注释风格来。Java 风格至少包含三行注释，中间一行是以*开始的,看上去比较整齐，干净。如下：

/*
 * 此处为注释内容
 * 注释内容
 */

多行注释基本和单行注释要求一样，额外，多行注释不能放在代码后面

// 推荐
if(isSelected){

  /*
   * 示例注释内容
   * 示例注释内容
   * 示例注释内容
   */ 
  opeate(); 
}

// 错误 注释没有用空行隔开
if(isSelected){
  /*
   * 示例注释内容
   * 示例注释内容
   * 示例注释内容
   */ 
  opeate(); 
}

// 错误 注释没缩进
if(isSelected){

/*
 * 示例注释内容
 * 示例注释内容
 * 示例注释内容
 */ 
  opeate(); 
}

// 错误 注释内容没缩进
if(isSelected){

  /*
   *示例注释内容
   *示例注释内容
   *示例注释内容
   */ 
  opeate(); 
}

// 错误 多行注释内容不能放在代码后面
if(isSelected){
  opeate();     /*示例注释内容*/
}

使用注释

写好注释，要搞清楚一点，就是该在哪里写注释，不该在哪里写注释。主要情况如下：

• 代码比较难懂的，直观不能理解的代码，有上下文联系的就需要加注释。
• 仅靠代码字面意思就明白的，就不需要加注释了。

注释不该将代码翻译一次，或者是不要显而意见的注释。例如：

// 错误
// sum代表数量
var sum=totalCount;

注释多用于解释代码的意图，和不明晰的意思。例如：

// 推荐
// sum主要传递计算过物品的总数，传给后台
var sum=totalCount;

以上就是常用注释的内容。如果你有用到js生成，推荐你参考YUI library的规范。