整洁代码--写好注释

写在标题前：看了很多资料说“写注释是为了弥补代码表达意图时的失败”，的确有道理，好的代码确实是不太需要注释的，但这种情况目前我只感觉是存在于理想中，现实中，尤其是国内，注释还是很重要的，注释写的清楚，能为阅读你代码的人提供很大的帮助，尤其是无法保证代码作者和阅读者英文水平不对等的情况下，中文注释显得尤为重要。千万弄明白注释与代码的关系：是画龙点睛、不是越俎代庖更不是画蛇添足！

1.不要花过多的时间维护注释，而是要去优化你的代码

如果你发现你的大量代码需要用注释进行描述，那你应该先修改好代码，好的代码需要少量点睛的注释，而不是靠大篇幅的注释进行描述。优化你的代码名称，代码结构最为重要！

2.应该添加的注释

2.1 法律信息

有时，我们的公司代码规范要求编写与法律相关的注释，在编写这类注释时，尽量指向一份标准的外部文档，而不是把条款全写在注释里。

2.2 对意图的注释

比如解释一下pojo类，以及一段正则表达式是做什么的，再或者是业务逻辑解释。这是最常用的注释。尽量写的言简意赅。

2.3 代码不可修改时的描述

在团队作业的情况下，肯定会遇到其他人写的代码，以及固定代码库，这类代码往往我们不能进行修改，所以如果觉得这些代码描述的不够清楚，为了将来方便自己理解，可以在此类代码中加入注释。

2.4 警示类注释

这类注释用于警告自己或其他程序员会出现某种后果。

2.5 TODO 注释

TODO 注释是一个程序员认为应该做的，但是由于某些原因目前还没做的工作。比如你需要写一个很长的业务逻辑判断时，但发现你还有5分钟就下班了，你就应该在这段业务逻辑上写上TODO类型注释，并在第二天完成它。

2.6 编写公共API时

良好的注释，以及说明会令使用者感激不尽。

3. 不好的注释

3.1 不知所云的注释

此类注释不是说作者不知所云，而是代码阅读者在没有上下语境的情况下看到这个注释完全不知道是在干什么，或者需要阅读很大很长一段代码之后才能理解。

3.2 多余的注释

此类注释描述的信息往往是应该由代码所表述的，再或者代码已经清楚的描述出来，而纯粹的复述性多余。

3.3 误导性注释

对于返回结果的描述，或者对于0代表什么1代表什么这类的描述，一定要准确，描述不清的注解写了还不如不写。

3.4 规矩性注释

例如每个函数都要有注释，即使这个注释并没有什么用，这种注释就不要写了，这就是多余的注释。

3.5 日志式注释

比如这段代码的修改者，修改时间，修改内容等。现在svn 等工具已经很方便了，这类注释应该淘汰了。
不过我还是在使用这种注释，可能我目前的工作环境适合这种，人不多的小组，当看到不明白的代码时，看到这是谁修改的或编写的，直接问就好了，但是大公司大项目可能不适合。因人而异吧。

3.6 括号后面的注释

比如有一个很长的try catch ，有时会在}后面加上//try  方便找到try的结尾，其实这时候可以考虑重构缩短函数了。

3.7 代码注释

注释掉代码这在编程中很正常不过了，但一定要给注释掉的代码及时处理，没有的代码就删除掉，如果觉得将来可能会用到那么请在注释中写明为什么而注释，因为随着时间的积累，越来越多的注释代码插在代码中，后续的程序员根本不敢删除它，却又不明白这一坨都是什么。

本文为阅读书籍、向资深程序员请教、以及自身摸索得出，如遇版权，请及时联系。
欢迎转载，但希望注明出处，谢谢。

整洁代码--写好注释相关推荐

java面试题25 在程序代码中写的注释太多，会使编译后的程序尺寸变大。
java面试题25 在程序代码中写的注释太多,会使编译后的程序尺寸变大. A:正确 B:错误蒙蔽树上蒙蔽果,蒙蔽树下你和我拿到这道题,我觉得说的贼有道理,注释太多,尺寸变大.无疑与就和驾考一样, ...
给代码写注释时有哪些讲究？
如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这肯定是之前同事"删库跑路"了. 看一份源码什么很重要?除了各种代码规范之外,还有一个比较重要的就是注 ...
整洁代码之道——重构
写在前面 \\ 现在的软件系统开发难度主要在于其复杂度和规模,客户需求也不再像Winston Royce瀑布模型期望那样在系统编码前完成所有的设计满足用户软件需求.在这个信息爆炸技术日新月异的时代,需 ...
夸奖对方代码写的好_我写出这样干净的代码，老板直夸我
一份整洁的代码对于一个系统是多么重要.如果代码写的乱七八糟,最后的结果就是无法对这些代码进行有效的管控.很有可能会毁掉这个系统. 什么才是整洁的代码? Biarne Stroustrup -[C++语 ...
代码洁癖系列（一）：什么是整洁代码
作为一个代码洁癖患者,我最大的愿望就是世界和平--对不起,拿错剧本了,最大的愿望就是将对代码的洁癖传播给每一个人,净化所有的代码.这是一个宏大的愿望,但我会一直努力净化我所看到的每一行代码,并且希望能 ...
代码整洁之道读书笔记——第一章：整洁代码
软件质量,不仅仅依赖于项目架构和项目管理,同样重要的是代码质量!!! 序神在细节之中,其实干什么事都一样,从小到大,一直明白一个道理:细节决定成败! 软件架构在开发中占据重要地位.其次,宏达建筑的最 ...
代码整洁之道--------整洁代码
软件质量不但依赖于整体的项目架构及项目管理,而且与代码质量紧密相关.书中有一个观点我觉得很对:代码质量与代码整洁度成正比.干净的代码,既在质量上较为可靠,也为后期的项目维护.迭代奠定了良好的基础. 一 ...
喜欢把代码写一行的人_我最喜欢的代码行
喜欢把代码写一行的人 Every developer has their favourite patterns, functions or bits of code. This is mine and ...
如何写好注释，让同事赞不绝口？
来源 | strongerHuang 如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这肯定是之前同事"删库跑路"了. 看一份源码什么很重要?除了各种 ...
如何避免把 Python 代码写得跟屎一样？
同样的功能,你可以使用不同的代码方式来实现,它们,都可以跑的起来,而在背后的那些「跳动」着的代码,有的美如诗,有的丑如屎...如果说,代码是有生命的,那么你希望它是温柔的天仙,还是抠脚的大汉? 你在 ...