Redirecting

注释那些事儿 - 前端代码质量系列文章(一)

18次 2019-01-11 zleader

02 什么是好注释,什么是坏注释

依据注释的准则,咱们应该以「能否协助阅览者更好地阅览了解代码」为标准,判断一个注释「是否有必要」。

好的注释包含:

  • 协助读者更好地了解代码逻辑和结构,例如:

init: function() { // 获取装备信息 const config = getConfig(); // 获取用户信息 const userInfo = getUserInfo(); // 依据装备和用户信息,进行初始化 doInit(config, userInfo); // 如果存在自定义装备时的特别逻辑 if (config.custom) {
    ...
  }
}
  • 特别或不易了解写法的解说阐明,例如:

/** 
 * parseInt was the reason my code was slow. 
 * Bitshifting the String to coerce it to a 
 * Number made it a lot faster. 
 */ const val = inputValue >> 0;
  • 特别符号注释:如 TODO、FIXME 等有特别意义的符号

  • 文件注释:部分规约会约好在文件头部书写固定格局的注释,如注明作者、协议等信息

  • 文档类注释:部分规约会约好 API、类、函数等运用文档类注释(如 jsdoc 风格)

  • 遵从一致的风格标准,如必定的空格、空行,以确保注释自身的可读性

坏的注释包含:

  • 注释对阅览代码无益:如本文第一个示例,本能够不用注释,用清晰的命名、逻辑进行代码自注释

  • 未遵从一致的风格标准:如单行注释长度、空格、空行,例如:

// bad 单行注释过长,不易阅览,应写成多行 // parseInt was the reason my code was slow.Bitshifting the String to coerce it to Number made it a lot faster. const val = inputValue >> 0; // good /** 
 * parseInt was the reason my code was slow. 
 * Bitshifting the String to coerce it to a 
 * Number made it a lot faster. 
 */ const val = inputValue >> 0;
  • 情绪性注释:如诉苦、轻视、搞怪等(被发现你就跪了)

03 怎么写好注释

注释规约

了解注释的目的和准则,制定并遵从一份注释规约,以确保注释的可读性和一致性

东西保障

比如运用 ESLint 确保注释风格的一致,运用 Sonar 查看项目注释率

04 注释规约

这儿给出一份可供参考的注释规约(参考自airbnb规约):

4.1 【引荐】单行注释运用//

注释应单独一行写在被注释对象的上方,不要追加在某条语句的后面:

// bad const active = true; // is current tab // good // is current tab const active = true;

注释行的上方需求有一个空行(除非注释行上方是一个块的顶部),以添加可读性:

// bad function getType() {  
  console.log('fetching type...'); // set the default type to 'no type' const type = this.type || 'no type'; return type;
} // good function getType() {  
  console.log('fetching type...'); // set the default type to 'no type' const type = this.type || 'no type'; return type;
} // good // 注释行上面是一个块的顶部时不需求空行 function getType() { // set the default type to 'no type' const type = this.type || 'no type'; return type;
}

4.2 【引荐】多行注释运用/** ... */,而不是多行的//

// bad // make() returns a new element // based on the passed in tag name function make(tag) { // ... return element;
} // good /**
 * make() returns a new element
 * based on the passed-in tag name
 */ function make(tag) { // ... return element;
}

4.3 【强制】注释内容和注释符之间需求有一个空格,以添加可读性。eslint:spaced-comment

// bad //is current tab const active = true; // good // is current tab const active = true; // bad /**
 *make() returns a new element
 *based on the passed-in tag name
 */ function make(tag) { // ... return element;
} // good /**
 * make() returns a new element
 * based on the passed-in tag name
 */ function make(tag) { // ... return element;
}

4.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;
  }
}

4.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;
  }
};

05 东西

咱们能够运用一些东西来确保注释质量,例如:

Eslint:确保一致的注释风格

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

Sonar:查看项目的注释率

Sonar 是一个代码持续集成渠道,它能够对代码进行静态扫描,得到项目的注释率数据。

注释率反应了注释行占总代码行的份额,注释率太低不好,但也不能盲目追求高注释率。

别的,同 Eslint 相似,Sonar 也有一些针对注释风格规矩能够装备。

06 跋文

了解注释的目的和准则,遵从一份注释规约并结合东西确保落地,能够使注释成为代码杰出的辅助,增强可读性和可维护性,然后进步代码质量。

推荐阅读

  • 基础科普!超全面的 UI 元素尺寸设置指南(上)

    基础科普!超全面的 UI 元素尺寸设置指南(上)

    开始着手设计手机界面时,困扰着新人的除了不知道应该在界面中放什么以外,最突出的就是不知道元素应该使用的长宽数值,也是学生问得最多的问题,所以着手整理2篇文章做扫盲,一次性搞明白,在手机的界面中如何设置元素的尺寸。

  • 我是如何将页面加载时间从6S降到2S的?

    我是如何将页面加载时间从6S降到2S的?

    网站设计的再优秀,功能再完美,但是响应的巨慢,用户的耐心很快会被耗光,这可能成为他最后一次访问,这绝对不是危言耸听,最近有幸参与到了公司海外站点项目,对于这点深有体会。

  • 百度网盘品牌升级背后的故事

    百度网盘品牌升级背后的故事

    百度网盘是百度提供的个人云存储服务,自2013年上线至今,通过强大的技术能力以及承担高额的带宽成本,为7亿用户提供文件存储、备份、分享、共享等服务,成为行业领先位置。 这5年里,我们从满足基础存储需求的一款工具,到现在越来越意识到高品质和情感化的体验对于用户的重要性。

竹鹿产品经理为您的项目进行一对一的策划及方案

懂设计,懂技术,更懂服务

立即沟通稍后再说

高端品牌网站 / 微信小程序 / 门户与平台开发 / OA协同办公 / 大数据 / VI与包装