代码注释有感

人是既勤劳又懒惰的动物，在第一行代码诞生之前，注定这世界上有数不清的代码注释写的很差或根本没有:(

聊到写代码，就不可避免的会涉及到一个让人欢喜让人忧的话题------注释。

代码最终是要给人看的，写注释的目的是让自己和别人能够更好的理解代码。这里也包括自己吗？是的，因为自己写的代码，过了一年后，难免不会忘记一些细节或特殊处理。但懒惰是人的天性，这也是人性的体现。我们看一份别人的代码时，总希望相关的说明文档尽量详细，函数说明尽量言尽其意。但是往往事与愿违，希望终归是希望，现实毕竟是现实。

程序员可能有很多理由不写注释。

首先，注释会增加程序员的工作量。我们在项目中有各种各样的事情要忙：忙着看别人的代码，忙着看相关的文档，忙着理解需求，忙着解决代码的各种崩溃及性能问题，忙着修改实现，忙着添加错误处理。。。。。。

程序员总是有很多的事情要忙，因此没时间写“不重要”的东西:)。

第二，需求可能总是在变更，以致于刚写完的注释就要修改，索性不写注释了。

第三，写到源文件里的中文很有可能变为乱码，但是英文又不好，因此不写了

那么既然程序员对于自己写注释如此的反感，以致于成为了群体默认的意识行为，是否有办法既能避免写注释，又能让代码一看就懂呢？

以下几种方法可能有帮助：

1.给变量、成员、函数等起个好名字

正如某位先哲所说，好的代码本身就是最好的说明文档。清楚明了的命名，让人一看名字就知道什么意思。不用进行任何解释。命名艺术某种程度上也体现了编码功力，因此要学会如何起名字。下面两种命名方法，哪种更好呢？

std::set<std::string> aaaa;

std::set<std::string> m_DeviceIdSet;

如果不是写个小的测试demo，本人一定不会使用第一种写法。第二种以m_开头，表示类成员，且仅看变量名就知道时保存设备Id的set结构。

如果使用第一种，需要看其它操作这个变量的代码，才能知道是什么意思。

2.一个函数尽量别太长（控制尽量别超过一屏）

有人不知道为什么一个函数最好不超过50行，或纠结于是否一个函数是否要超过50行。因为我们使用的正常屏幕，在字体大小正常的情况下，最多能显示大概50行代码。如果函数超过一屏，翻页会影响阅读代码的效率。在一个屏幕内的代码，程序员会专心的理解当前函数的功能。当函数过长时，函数内部逻辑复杂度会大概率增加，进而增加理解与重构代码的难度。没人会保证自己写的代码不会被修改。几百上千行的函数，维护时简直是噩梦。

一定要强迫不超过一屏吗？这不是绝对的，比如某些表示数据实体的数据结构可能有很多字段，对这些字段初始化或赋值的函数超过一屏是没问题的。这样的函数一般都没有复杂的逻辑。

3.无用的代码最好去掉

包括变量、函数、函数参数、结构定义等等，不需要就去掉，否则可能trace代码半天发现根本没用到，耽误时间。

4.某些情况下不推荐写注释

有些代码注释不是必须的。代码本身带有自注释属性，写注释有时反而会画蛇添足。另外，如果无论何时能保证注释与所写代码（包括修改的）完全一致那么推荐写注释，否则反而可能会引起误解。

5.增加必要日志

一些代码路径上可增加日志以起到说明的目的。------程序员也不愿意写日志:D

6.尽量使用设计模式

虽然设计模式不是万能的，但毕竟是几十年下来软件工程领域的前辈们总结出来的经验教训，使我们可以少走弯路。但如果不能很好的应用设计模式，那还是最好别用了，否则会适得其反。

在我看来，编程是一项极能体现个体差异的工作，就像一千个人有一千个汉姆雷特。并且编程过程本身非常容易出错，好在有众多的工具能够帮助我们少犯错误。因此，多掌握一些工具的用法还是很有帮助的，比如：代码对齐工具、UML工具、代码检查工具、代码重构工具等等。

最后祝大家在编程的道路上少些痛苦，多些快乐！