老生常谈：注释怎么写？

整理自知乎上我的一次回答。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函数，也应该看到我加粗了“选择”二字），这是选择排序。

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

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

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