前台注释那些事儿:看懂这篇,提高代码质量So easy

作者 : 开心源码 本文共2675个字,预计阅读时间需要7分钟 发布时间: 2022-05-11 共171人阅读

前言:

?好的注释能提高代码的可读性和可维护性,从而提高代码质量。那么什么是好的注释?如何写出好的注释?

好的注释能提高代码的可读性和可维护性,从而提高代码质量。

那么什么是好的注释?如何写出好的注释?本文将从注释的目的和准则出发对 JS 注释进行讨论。

一、注释的目的和准则

注释的目的:

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

注释的准则:

如无必要,勿增注释 ( As short as possible )

如有必要,尽量详尽 (?As long as necessary )

「如无必要,勿增注释」是指注释要避免过多过滥,不要为了注释而注释。多余的注释等价于冗余的代码,除了对添加可读性无益,一旦代码需要修改,修改注释也会是一大负担。

我们应当追求「代码自注释」,即代码本身就拥有较高的可读性(通过清晰的命名、正当的结构等)。举个例子:

// bad // 假如已经准备好数据,就渲染表格 if (data.success && data.result.length > 0) { ?renderTable(data); ? } // good const isTableDataReady = data.success && data.result.length > 0; if (isTableDataReady) { ?renderTable(data); }

「如有必要,尽量详尽」是指需要注释的地方应该尽量详尽地去写,以让阅读者能充分理解代码的逻辑和用意为标准。

二、什么是好注释,什么是坏注释

根据注释的准则,我们应该以「可以否帮助阅读者更好地阅读了解代码」为标准,判断一个注释「能否有必要」。

好的注释包括:

帮助读者更好地理解代码逻辑和结构,例如:

特殊或者不易了解写法的解释说明,例如:

特殊标记注释:如 TODO、FIXME 等有特殊含义的标记

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

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

遵循统一的风格规范,如肯定的空格、空行,以保证注释自身的可读性

坏的注释包括:

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

未遵循统一的风格规范:如单行注释长度、空格、空行,例如:

情绪性注释:如抱怨、歧视、搞怪等(被发现你就跪了)

小编推荐,前台学习交流群 330336289 ?邀请码:寂静!

三、如何写好注释

注释规约

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

工具保障

比方用 ESLint 保证注释风格的一致,用 Sonar 检查项目注释率

四、注释规约

这里给出一份可供参考的注释规约:

1.【推荐】单行注释用?//

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

// bad

const active = true; // is current tab

// good

// is current tab

const active = true;

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

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

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

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; ?} }

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; ?} };

五、工具

我们能用少量工具来保证注释质量,例如:

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 也有少量针对注释风格规则能配置。

后记

“Comment or not comment, that is the question”

了解注释的目的和准则,遵循一份注释规约并结合工具保证落地,能使注释成为代码良好的辅助,加强可读性和可维护性,从而提高代码质量。

?

             

说明
1. 本站所有资源来源于用户上传和网络,如有侵权请邮件联系站长!
2. 分享目的仅供大家学习和交流,您必须在下载后24小时内删除!
3. 不得使用于非法商业用途,不得违反国家法律。否则后果自负!
4. 本站提供的源码、模板、插件等等其他资源,都不包含技术服务请大家谅解!
5. 如有链接无法下载、失效或广告,请联系管理员处理!
6. 本站资源售价只是摆设,本站源码仅提供给会员学习使用!
7. 如遇到加密压缩包,请使用360解压,如遇到无法解压的请联系管理员
开心源码网 » 前台注释那些事儿:看懂这篇,提高代码质量So easy

发表回复