老生常谈：注释怎么写？

整理自知乎我的一次回答：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. 将最小元素放在有序数组的最后面（或者最前面）

 

不用我多解释，你一眼就知道（看我加粗的字），这是选择排序。

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

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

 

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