老生常谈：注释怎么写？

整理自知乎上我的一次回答。http://www.zhihu.com/question/20594192

我的观点，只写说明性注释，不写功能性注释。也就是说，注释Why，而不是How和What。

类和函数多写文档注释，多少行无所谓，写在最前面，只要你是注释的Why。

函数内部，尽量少写注释。如果你的代码需要写注释来说明他的功能，那么这段代码就需要重构，最简单的方法，最简单的方法：提取函数。这样的好处是，函数名就是注释。一个错误的观点就是 注释是给人看的，程序是给电脑看的。其实，程序是给人看的，凑巧的是，它居然可以在电脑里运行。

《重构:改善既有代码的设计》一书写道：

每当感觉需要以注释来说明点什么的时候，我们就把需要说明的东西写进一个独立函数中，并以其用途（而非实现手法）命名。

每次我给别人讲解「选择排序」、「插入排序时」，他们都觉得太难了，而且几乎每本数据结构教科书都是写了一堆代码和注释，这丝毫没有降低这个算法的难度。

如果不写注释，而写成函数呢？

伪代码：

array_ordered = []
loop_all_element(array, function(i){
el = select(array[i+1, array.length])
push(array_ordered, el)
......
})

1. 构建一个有序数组，初始为空，（ps：空集都是有序集）。
   
2. 循环整个数组，进行如下操作：
   
3. 从数组剩下的元素里面选择最小的（或最大的）
4. 将最小元素放在有序数组的最后面（或者最前面）

不用我多解释，你一眼就知道（即使你看不到select函数，也应该看到我加粗了“选择”二字），这是选择排序。

插入排序呢？大同小异，我就不详细写了。

所以，文档注释，多少无所谓。函数内、类内注释，能不写，就不写。

相关阅读：千万要避免的五种程序注释方式

7楼longshengguoji昨天 17:13

没有注释，别人读起来是很不方便的

Re: JustJavaC昨天 17:42

回复longshengguojin代码是应该是自解释的。如果别人看不懂，那么请重构你的代码。

6楼u010197502昨天 15:21

自己编写的老程序,功能性注释能大大节约阅读时间.勤快还是不吃亏的.

5楼Yalishizhude昨天 14:00

是的，有注释绝对不是什么坏事，而且代码找起来也方便

4楼u010209680昨天 12:02

学习中

3楼loogloogcom昨天 11:20

一下能看懂的注释是好注释，就这么简单。n最好，代码本身就是注释nn注释太多，不是好事情。

Re: JustJavaC昨天 11:30

回复loogloogcomn对。注释是写给人看的，其实，代码也是写给人看的。nn既然都是写给人的，还是用代码直接传达意思的好，少写注释，毕竟屏幕有限，如果注释太多，那么看到的代码就越少。

2楼wswg1987昨天 09:08

不知道你为什么有这个观点，类或者函数里面最好还是加上注释吧，其实注释不仅仅是给别人写的更加是给自己看的，写一行注释也消耗不了多少时间，假如你几年前写的代码现在叫你做个优化，你只看类或者函数的开头注释不觉得累吗，所以注释尽量还是写清楚吧。楼主别误人哦

1楼savechen2012昨天 15:52

函数外注释，说的不错