3.注释(代码的整洁之道)
3.注释(代码的整洁之道)
目录
- 注释不能美化糟糕的代码
- 用代码来阐述
- 好注释
- 坏注释
注：代码的整洁之道PDF： https://pan.baidu.com/s/16PLDWPiusGjcUfW_jgOm5w 密码: s708
1. 注释不能美化糟糕的代码
- 什么也不会比乱七八糟的注释更有本事搞乱一个模块，什么也不会比陈旧、提供错误信息的注释更有破坏性。
- 注释的恰当用法是你不我们在用代码表达意图时遭遇的失败。
- 如果你发现自己需要写注释，再想想看是否有办法翻盘，用代码来表达。
- 注释会撒谎，存在的时间越久，就离其所描述的代码越远，越来越变得全然错误。原因很简单，程序员不能坚持维护注释。
- 代码在变动，在演变，但注释却不能随之变动。
- 真实只在一处地方有：代码。只有代码能忠实地告诉你它该做的事情。所以，尽管有时需要注释，也该多花心思尽量减少注释量。
2. 用代码来阐述
- 示例一
- 示例二
- 你更愿意看到哪个示例？
- 只要想上几秒钟，就能用代码解释你大部分的意图。很多时候，简单到只需要创建一个描述与注释所言同一事物的函数即可。
3. 好注释
- 有些注释是必须的，也是有利的。不过要记住，唯一真正好的注释是你想办法不去写注释。
1. 法律信息
- 公司代码规范要求编写与法律有关的注释，例如，版权及著作权声明就是必须和有理由在每个源文件开头注释防止的内容。
2. 提供信息的注释
- 有时注释提供基本信息也有用处，例如，以下注释解释了某个抽象方法的返回值：
- 这类注释有时很管用，但更好的方式是尽量利用函数名称传递信息。比如，在本例中，只要把函数重新命名为responderBeingTested，注释就是多余的了。
3. 对意图的解释
- 有时，注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图。
4. 阐释
- 有时，注释把某些晦涩难明的参数或返回值的意义翻译为某种可读形式，也会有用的。
- 通常，更好的方法是尽量让参数或返回值自身就足够清楚。但如果参数或返回值是某个标准库的一部分，或是你不能修改的代码，帮助阐释其含义的代码就会有用。
5. 警示
- 有时，用于警告其他程序员会出现某种后果的注释也是有用的。
6. TODO注释
- TODO注释解释了为什么该函数的实现部分无所作为，将来应该是怎样。
- TODO是一个程序认为该做，但由于某些原因目前还没做的工作。
6. 放大
- 注释可以用来放大某种看来不合理之物的重要性。
4. 坏注释
- 大多数注释都属于此类。通常，坏注释都是糟糕的代码的支撑或借口，或者对错误决策的修正，基本上等于程序员自说自话。
1. 喃喃自语
- 如果只是因为你觉得应该或者因为过程需要注释，那就是无谓之举。如果你决定写注释，就要花必要的时间确保写出最好的注释。
2. 多余的注释
- 下面代码展示了简单函数，其头部位置的注释全属多余，读这段注释花的时间没准比代码花的时间还要多。
3. 误导性注释
4. 循规式注释
- 所谓每个函数都要有javadoc或每个变量都要有注释的规矩全然是愚蠢可笑的。这类注释只会搞乱代码，有可能误导读者。
5. 日志式注释
6. 废话注释
7. 可怕的废话
8. 能用函数或变量时就别用注释
- 代码一
- 可改成以下没有注释的版本
- 作者应该重构代码，而不是写注释。
9. 位置标记
程序员喜欢在源代码标记某个特别位置。如
把特定函数放在这种标记栏下，多数时候实属无理，理当删除。
10. 括号后面的注释
- 有时，程序员会在括号后面放置特殊的注释，尽管对含义深度嵌套结构的长函数可能有意义，但只会给我们更愿意编写的短小、封装的函数带来混乱。
- 如果你发现自己想标记右括号，其实应该做的是缩短函数。
11. 归属与署名
- 源代码控制系统非常清楚谁在何时添加了什么，没必要用那些小小的签名搞脏代码。
- 注释在那放了一年又一年，越来越不准确，越来越和原作者没关系。
12. 注释掉的代码
- 直接把代码注释掉是讨厌的做法，别那么干！
13. HTML注释
- 源代码注释中的HTML标记是一种厌物。
14. 非本地信息
- 假如你一定要注释，请确保它描述了离它最近的代码。别在本地注释的上下文环境中给出系统级的信息。
15. 信息过多
- 别在注释中添加有趣的历史性话题或者无关的细节描述。
16. 不明显的联系
- 注释及其描述的代码之间的联系应该显而易见。
17. 函数头
- 短函数不需要太多描述，为只做一件事的短函数选个好名字，通常比写函数头注释要好。
18. 非公共代码中的javadoc
19. 范例
3.注释(代码的整洁之道)相关推荐
- 2.函数(代码的整洁之道)
2.函数(代码的整洁之道) 目录 短小 只做一件事 每个函数一个抽象层次 switch语句 使用描述性的名称 函数参数 无副作用 分隔指令与询问 使用异常代替返回的错误码 别重复自己 结构化编程 如何 ...
- 1.有意义的命名(代码的整洁之道)
1.有意义的命名(代码的整洁之道) 目录 名副其实 避免误导 做有意义的区分 使用读的出来的名称 使用可搜索的名称 避免使用编码 避免思维映射 类名 方法名 每个概念对应一个词 别用双关语 使用解决方 ...
- 四月书单--《你一年的8760小时》，《代码的整洁之道》
当你深刻的认识到自己的不足时,就会激发无限的潜能.成为一个优秀的自己.前几天和发小聊天,她告诉我,一年前想通了一件事,只和过去的自己比较.从农村来到北京的她曾经因为别人的辉煌而不自信,但是庆幸她能告诉 ...
- 开课吧：分享C++代码的整洁之道！
大家好,今天分享的主题是:C++代码整洁之道. 整洁的代码在团队中无疑是很受欢迎的,可以高效的被其它成员理解和维护,本文参考<C++代码整洁之道>和<Google C++编码规范&g ...
- 《Clean Code》代码的整洁之道（一）
<代码整洁之道>:细节之中自有天地,整洁成就卓越代码 概述 软件质量,不但依赖于架构及项目管理,而且与代码质量紧密相关.这一点,无论是敏捷开发流派还是传统开发流派,都不得不承认.<代 ...
- 架构整洁之道 pdf_代码有整洁之道，而架构同样有整洁之道
大家好!我是超级机器人 UltraBot,今天给大家一些值得阅读的开源书籍和项目. Etcd3 学习笔记 etcd 是一个分布式一致性键值存储,用于共享配置和服务发现.etcd 是 Go 编写,并使用 ...
- 前端代码的整洁之道 | 技术头条
在前端开发过程中,你有没有遇到过由于代码交互太多太重时,想改动一行代码"牵一发而动全身":使用框架很爽,可框架绑定应用却很麻烦?那么如何解决呢? 你需要"前端整洁&quo ...
- 《代码整洁之道》阅读笔记 4注释
"Comments Do Not Make Up for Bad Code."(注释不是对劣质代码的补救).事实上好的代码即便没有注释也拥有良好的可读性,但恰当的注释会让代码变得更 ...
- 重读【代码整洁之道】
一.前言 [代码整洁之道]很经典,但也有些过时,翻译上也有些啰嗦,但总体上是好书.通过对本书核心内容的摘抄,结合自己的经验,整理了一些精简的点,这样你就省的去啃那本400多页的书了. 软件质量 = 架 ...
最新文章
- 宝塔linux_宝塔面板建站基础教程：如何安装宝塔面板及建立博客网站
- nova ERROR (ClientException): 解决方法
- 转载-IronPython入门：什么是IronPython？
- 使ALV控件中的内容可编辑
- SQL Servr 2008空间数据应用系列三：SQL Server 2008空间数据类型
- datatype未定义是什么意思_vue.js一直提示未定义
- Cobra命令行框架及使用
- 人工智能的下个十年在推理？
- Excel数据透视表经典教程十三《打印数据透视表/图》
- moodle4.04无法上传中文文件名
- 组件上传之AspUpload使用方法
- 计算机屏幕出现条纹w7,电脑重装win7后屏幕出现条纹怎么办
- 前度控制器源代码分析
- oracle中的nls在哪,Oracle nls_sort和nlssort 排序功能介绍
- 云计算的特点包括哪几方面？
- 私有部署、重构企业软件，第四范式发布大模型“式说”
- 不是抽象类的基类不是好基类
- Hadoop基础操作--查询集群的计算资源信息
- python常量基本类型有哪些_【Python③】python基本数据类型，变量和常量
- python爬取qq空间说说