深知大多数程序员,想要提升技能,往往是自己摸索成长,但自己不成体系的自学效果低效又漫长,而且极易碰到天花板技术停滞不前!
既有适合小白学习的零基础资料,也有适合3年以上经验的小伙伴深入学习提升的进阶课程,涵盖了95%以上鸿蒙开发知识点,真正体系化!
由于文件比较多,这里只是将部分目录截图出来,全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、讲解视频,并且后续会持续更新
- 【代码整洁之道】格式篇(待发布)
- 【代码整洁之道】对象和数据结构篇(待发布)
- 【代码整洁之道】错误处理篇(待发布)
- 【代码整洁之道】单元测试篇(待发布)
- 【代码整洁之道】迭代篇(待发布)
说明:该专栏【代码整洁之道 - 理论与实践】未来也会持续围绕代码整洁去展开更多更深入的内容,也欢迎大家点赞和关注哦~😊😊😊
理论篇
相信我们平时的开发中,多多少少都会加一些代码注释,用于去说明对应的代码片段的含义,优雅的注释一定是会有助于代码理解的,但是这里想强调两点:
- 注释本质上是为了弥补我们直接用代码来表达意图的不明确性,其目的还是服务于代码,因此,我们关注的核心依然是代码,如果能用优雅的代码清晰的表达含义的时候,就没必要再使用注释,同时,我们在写代码的时候,也要尽可能做到用简洁清晰的代码逻辑,而不是用大量的注释来弥补那些糟糕的代码。
- 注释也是需要专门去维护的,随着需求的不断迭代,注释很可能也是需要不断去更新的,如果不去维护,时间越久,注释的含义与最新代码的含义差的越远,反而引起歧义
总结下来就是:注释,不能美化糟糕的代码
,接下来,我们就看看平时开发中可能多多少少会遇到一些好注释和坏注释。
好注释
到底哪些是好注释呢?或者哪些地方需要我们去写注释呢?
法律信息
有时候,公司代码规范要求必须编写与法律相关的注释,例如:版权,著作权等,一般都需要在文件的头部去添加相关法律信息的注释。或者我们平时相关去开源自己相关的一些工具或者库的时候,都可以在文件头部加这样的注释,这也是推荐的。
例如:看一下react的源代码文件中:
公共API的注释
有时候,比如一个方法可能会出现一些晦涩难懂的参数以及返回值等,这时,我们也可以添加注释,去说明各个参数的含义,以及返回值的含义等。例如:lodash源代码中的各个方法:
注意:一般在编写一些工具库或者公共方法的时候,我们一定要把相应的注释都加上,这样其他人在调用你写的这个工具的时候,才能够去更好的理解去怎么使用, 或者我们在项目中,要抽象一个公共的组件的时候,也需要去把各个prop,event的含义去通过注释的方式去阐述清楚。
当然,不止公共方法,如果我们平时业务开发中,如果有些方法逻辑比较复杂,这时,我们要首先想能不能尽可能去优化代码的逻辑,其次再去考虑是否有必要添加一些注释。
TODO注释
通过TODO注释,可以在项目中,把一些暂未实现的功能列表等通过TODO注释的形式来记录一下。
警示作用
开发中,可能有些代码逻辑可能会导致某种后果,这时,我们也需要去添加注释去说明一下,从而对看到这段代码的程序员起到一个警示作用。
其实,不仅仅是警示作用,代码中,任何情况下,如果确认在代码逻辑已经足够好,但是依然需要去说明一下的情况下,我们都可以去通过添加注释的形式,去说明或者强调一下。
坏注释
注释不认真对待
// bad case
// 获取列表
function getTastList() {
//...
}
相信我们平时开发中,大多数都会写过上面这种注释,但其实上面的代码犯了两个错误:
- 多余的注释:上面这个方法getTaskList已经能够通过方法名比较清晰的明白该方法的作用啦,就是获取任务列表。没必要再加注释,注释的作用是为了弥补代码表达的不足,不是每段代码都要加注释,反而是能用代码表达清晰的,就不必再加注释。
- 误导性注释:既然你选择加注释,那就认真对待注释,加了可以起到效果,不要把注释写的模棱两可,或者可有可无,假如文件中还有一个获取其他列表的方法,那是不是就有歧义啦。
这里只是想强调一下,我们一定要认真对待注释,同时尽可能写的完整和清晰。否则很可能起到反作用。
哪里都加注释
可能团队要求加注释了,于是乎就尽可能的能加注释就全部加了,不管有没有必要,哪里都加,这更是不推荐的,注释的维护也是有成本的,我们反而是应该能用代码表达的就只用代码,尽可能不用注释。
日志式注释
有时候,有些文件可能修改比较频繁,于是会就把所有的修改记录全部添加到注释中,其实也是没有必要的,时间长了,只会越来越冗余。
注释掉的代码
这个大家肯定都做过,某些功能或者代码可能暂时需要隐藏,于是直接把对应的代码注释掉,对于自己来说,可能是更方便啦,但是对于别人啦,当别人看到一段代码注释掉啦,肯定有产生疑问?这段代码是否还有作用,能不能删等?而且注释的代码越多,整体代码质量就会越差。 因此,如果有需要暂时隐藏的功能,我们直接把对应的功能删除即可,其实重新找回来也是很容易的,从git历史版本等可以很轻易的找出来。
非本地注释
也就是说 我们写注释时,一定要确保描述了离它最近的代码,而不是在当前地方描述另外一个地方的代码。
注释信息过多
注释的信息过多,也没人愿意看,不仅代码,注释也要简洁,能够说明问题即可。
总结:以上不管是好注释还是坏注释,都可能是我们平时开发中,可能遇到的,也可能就是自己写的,我们通过这节的学习,至少知道了哪些注释是好的,哪些是坏的,以后,我们要可能避免写出这些还注释。总结起来一句话;能用优雅的代码表达,就不要用注释,如果必须加注释,一定要认真去维护和书写注释。
规范篇
【必须】使用/* … */进行多行注释
// bad case
// getNumber() return a new number
// @param {Number} number
// @return {Number} number
function getNumber(number) {
return number;
}
// good case
/*
* getNumber() return a new number
*/
function getNumber(number) {
return number;
}
【必须】 /** ... */
风格(首行有两个 *)的块级多行注释仅能被用于 JSDoc。
也就是说:我们上面第一点提到的多行注释,首行是使用单* 的,这种方式相当我们可以自定义的格式自由组织注释的内容,但是如果使用首行双*的话,仅能被用于Jsdoc, Jsdoc是什么呢?官网链接如下:JSDoc官网, 简单理解为它就是一个根据javascript文件中注释信息,生成JavaScript应用程序或库、模块的API文档 的工具。后面还会详细讲一下其使用。
// good case
/**
* getNumber()
* @description: 描述
* @params {类型} 参数名 Must
* @params {类型} 参数名 Optional
* @returns {类型}
*/
function getNumber(number) {
return number;
}
拓展:当我们写一些公共工具库或者函数的时候,可以推荐使用该JSDoc,可以帮助我们更规范的生成注释内容。
【推荐】使用//进行单行注释
除此之外,还有两点要注意:
- 一般将单行注释放在需要被注释的行的上面新行。
- 建议在注释之前放一个空行,除非它在块的第一行。
注意:通过前面的理论篇的学习,大家再看下面这些代码的时候,很可能产生这样一个疑问:下面好多代码的注释都是无用注释呀,本身命名已经很好的说明其含义啦,没必要再加注释,哈哈哈,是的,你说的非常对,也说明你掌握了对理论篇的内容哈,而下面的case只是从代码规范的角度,看注释放到哪里比较合适,以及注释的格式怎么样比较规范,而注释的具体内容,以及是否需要注释不是本节的关注点。
// bad case
const username = 'kobe'; // username: 用户名
// good case
// username: 用户名
const username = 'kobe';
// bad case
function getNumber(number) {
console.log('get number...');
// 把参数赋值给变量
const num = number;
return num;
}
// good case
function getNumber(number) {
console.log('get number...');
// 把参数赋值给变量
const num = number;
return num;
}
// good case
function getNumber(number) {
// 获取number
console.log('get number...');
const num = number;
return num;
}
【必须】使用一个空格开始所有的注释,不管是单行还是多行。
// bad case
//username: 用户名
const username = 'kobe';
// good case
// username: 用户名
const username = 'kobe';
**深知大多数程序员,想要提升技能,往往是自己摸索成长,但自己不成体系的自学效果低效又漫长,而且极易碰到天花板技术停滞不前!**
![](https://img-blog.csdnimg.cn/direct/743b668910224b259a5ffe804fa6d0db.png)
![img](https://img-blog.csdnimg.cn/img_convert/949e7a53d24c14acad7e60b5fc0128dd.png)
![img](https://img-blog.csdnimg.cn/img_convert/84aafb08b3f595f0c775269712a40752.png)
**既有适合小白学习的零基础资料,也有适合3年以上经验的小伙伴深入学习提升的进阶课程,涵盖了95%以上鸿蒙开发知识点,真正体系化!**
**由于文件比较多,这里只是将部分目录截图出来,全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、讲解视频,并且后续会持续更新**
**[需要这份系统化的资料的朋友,可以戳这里获取](https://bbs.csdn.net/topics/618636735)**
mg-Xz4nsAY0-1715657813682)]
[外链图片转存中...(img-UHtIrbQc-1715657813682)]
**既有适合小白学习的零基础资料,也有适合3年以上经验的小伙伴深入学习提升的进阶课程,涵盖了95%以上鸿蒙开发知识点,真正体系化!**
**由于文件比较多,这里只是将部分目录截图出来,全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、讲解视频,并且后续会持续更新**
**[需要这份系统化的资料的朋友,可以戳这里获取](https://bbs.csdn.net/topics/618636735)**