前端注释那些事儿:看懂这篇,提高代码质量So easy
前言:
好的注释可以提高代码的可读性和可维护性,从而提高代码质量。那么什么是好的注释?如何写出好的注释? 好的注释可以提高代码的可读性和可维护性,从而提高代码质量。
那么什么是好的注释?如何写出好的注释?本文将从注释的目的和原则出发对 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); } 「如有必要,尽量详尽」是指需要注释的地方应该尽量详尽地去写,以让阅读者可以充分了解代码的逻辑和意图为标准。
二、什么是好注释,什么是坏注释
根据注释的原则,我们应该以「能否帮助阅读者更好地阅读理解代码」为标准,判断一个注释「是否有必要」。
好的注释包括:
帮助读者更好地了解代码逻辑和结构,例如:
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;
情绪性注释:如抱怨、歧视、搞怪等(被发现你就跪了)
做为一名前端程序员,有一个学习的氛围跟一个交流圈子特别重要。这是我的一个前端学习交流群 330336289(邀请码:寂静),想学习交流前端,打算深入了解这个行业的朋友,不管你是小白还是大牛都欢迎加入,大家一起交流学习。
三、如何写好注释
注释规约
理解注释的目的和原则,制定并遵循一份注释规约,以保证注释的可读性和一致性
工具保障
比如使用 ESLint 保证注释风格的一致,使用 Sonar 检查项目注释率
四、注释规约
这里给出一份可供参考的注释规约:
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; }
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
pgc-image/152531852952604e64de90b
请点击此处输入图片描述
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”
理解注释的目的和原则,遵循一份注释规约并结合工具保证落地,可以使注释成为代码良好的辅助,增强可读性和可维护性,从而提高代码质量。
转载于:https://juejin.im/post/5aea8715f265da0b8a6773b1
前端注释那些事儿:看懂这篇,提高代码质量So easy相关推荐
- 看懂这篇文章,你就懂了信息安全的密码学
看懂这篇文章-你就懂了信息安全的密码学 一.前言 一个信息系统缺少不了信息安全模块,今天就带着大家全面了解并学习一下信息安全中的密码学知识,本文将会通过案例展示让你了解抽象的密码学知识,阅读本文你 ...
- 谷歌最新开源前端框架了解一下?前端小白都能看懂的8本书
导读:跨平台.免费.开源,谷歌又搞"大新闻"?谷歌最新前端开发框架Flutter1.0版本已发布,可以极速构建漂亮的原生应用.各位前端大神都在用什么开发?下面八本书会帮助你快速入门 ...
- web页面中如何隐藏js代码的显示。或者说如何不让别人一下子就能看懂我的web代码。
今天在看别人网页页面的时候,在百度搜索结果中的页面中右键查看源代码,发现百度搜索结果就只有两个代码,如下,没出现其他任何代码 <!DOCTYPE html> <!--STATUS O ...
- 入门响应式Web?看懂这篇文章就够了!——Web前端系列学习笔记
文章目录 视口基础知识 视口概念 视口基本属性 meta 标签 视口应用实例 媒体查询基础知识 媒体查询概念 demo1-媒体查询 demo1效果 百分比布局 百分比布局概述 demo2-百分比布局 ...
- 入门JavaScript?看懂这篇文章就够了!——Web前端系列学习笔记
文章目录 JavaScript简介 什么是JavaScript? JavaScript的构成 JavaScript特点 JavaScript基础知识 JavaScript的引入方式 1. 将JS代码嵌 ...
- 苦练基本功《如何阅读看懂一篇Datasheet》
如何阅读一篇datasheet 第一篇 第二篇 第三篇 三篇文章均为转载,总结三篇如下 第一篇:http://blog.csdn.net/kobesdu/article/details/1690568 ...
- 想要网上赚钱,看懂这篇就够了
最近更文频率明显变慢了,不是懒,而是新上的两个项目着实有太多的东西需要去布局.引流方法需要去实践,引流软件需要去测试,引流视频需要去录制,项目相关的方方面面的资源都需要去搜集.进来的学员需要去辅导, ...
- 如何看懂一篇学术论文
论文结构: 摘要(abstract) 导言(introduction) 方法(methods) 结果(results) 结论或解析.讨论(conclusions/interpretations/dis ...
- 看懂这篇,至少关于Redis的面试你不用担心了
絮叨 之前一直在熬夜的大环境下码文,所以我自己觉得质量有所下降,我这不一睡好就加班加点准备补偿大家,来点干货.(熬夜太容易感冒了) 顺带提一嘴,我把我准备写啥画了一个思维导图. 这篇我就先放出来大家看 ...
- 让别人和自己看懂自己的程序代码?一文掌握Java单行多行、文档注释以及注解(Annotation)超详细的理解使用,IDEA注释注解快捷键和模板,提高程序代码更有可读性
文章目录 单行和多行注释 文档注释(Java特有) Annotation(注解)的理解 常见的Annotation示例 IDEA注释注解快捷键及模板 自定义 Annotation JDK 中的元注解 ...
最新文章
- 在人工智能领域,人工智能机器无法如人一样理解常识知识
- android selector下的设置背景属性值
- yolov5剪枝开源分享
- torchvision 笔记:ToTensor()
- 停止对互联网的意淫吧,它不过是个信息技术啊
- Spring-AOP实现的两种方式
- boost::hana::index_if用法的测试程序
- 【Ubuntu】 Ubuntu16.04搭建NFS服务
- 前端学习(2454):用户登录
- 上海电力学院计算机学院怎么样,上海电力学院计算机科学与技术学院在职研究生_上海电力学院在职研究生_在职研究生招生信息网...
- 0基础lua学习(二十)Lua单例
- 限时购校验小工具dubbo异步调用实现限
- 一个快速排序写了快 10000 字?
- 反思风险管理的五项核心风险。
- Java程序员必看!java后端开发实例
- CS 188 Project3(RL) Q7:Epsilon Greedy
- php必应壁纸 分辨率,必应壁纸php获取接口
- scikit-opt的使用
- 配置mpls vpn MCE组网
- 30个最值得去的人间仙境
热门文章
- 计算机组装与配置答案,解答电脑组装配置有哪些
- hawk物联网组态工具_物联网web组态网关在智慧农业中的应用
- ValueError: The truth value of a Series is ambiguous. Use a.empty, a.bool(), a.item(), a.any()
- oracle多边形经纬范围筛选_Oracle数据库之Oracle spatial空间查询的选择度分析
- 电脑太慢了最简单的办法怎么弄_最简单的电脑端微信多开方法
- leetcode 859. Buddy Strings
- 【知识图谱系列】知识图谱的神经符号逻辑推理
- 模拟https类型的get,post请求时,碰到证书不信任,无法正常获取返回内容的异常
- 为什么选择红黑树作为底层实现
- 不变子空间与线性变换的矩阵之间的关系