《编写可维护的JavaScript》(二) ---注释

注释

单行注释

独占一行的注释用来解释下一行代码

1. 注释之前总有空行,且缩进层级和下一行保持一致
2. 在代码尾部注释时,与代码尾部之间至少有一个缩进,超过当前行的最大字符限制,需要将注释移动到上方

//bad 注释之前没有空行
if(isSame){
    //如果代码执行到这里表示通过了安全检查
    allowed();
}
//bad 代码与注释之间没有缩进
if(isSame){
    allowed();//如果代码执行到这里表示通过了安全检查  与代码之间添加空格
}

多行注释

以/*开头并独占一行,以*/结尾并独占一行,注释内容以*开头

多行注释前应该有一个空行

多行注释的缩进和要解释的代码一致

/*
* 这是第一行注释
* 这是第二行注释
*/

什么时候使用注释

通用原则是: 当代码不够清晰时,添加注释

//bad
​
// 初始化count
var count = 10;
​
​
//good
​
// 修改count会让链接跳转失败
var count =10;

在没有注释的情况下,万一修改了count,谁能想到他会让链接跳转失败呢? 这就是添加注释的原因,描述必要的信息.以下情况都应该使用注释:

1. 难于理解的代码

   /*
   * 如果mode为2时,这里只执行依次递归,用来执行对象到对象的合并操作,原型到原型的操作将不被执行
   */
   if(mode === 2){
       Y.mix(.....)
   }
   ​
   顺便一提: 这里使用解释变量感觉更合适
   const canMergTwoObj = mode === 2;
   if(canMergTwoObj){
       Y.mix(.....)
   }
   

2. 可能被认为是错误的代码: 在团队中,总有一些好心的开发者在编辑代码的时候发现他人的错误,就立即修复他,有时这并不是错误的源头,就导致引发更多的错误

   while(ele && (ele = ele[axis])){ //赋值操作
       ...
   } 
   

文档注释

就想下面的例子一样,为所有的方法,构造函数,包含多个文档注释的方法的对象,添加文档注释.注释的详细风格和用法需要根据最终选择的文档生成工具有关

/**
 * @description: 
 * @param {*} param1
 * @param {*} param2
 * @return {*}
 */
function showJSDoc (param1,param2){}

如果文章对你有帮助,留个赞鼓励支持一下吧~