整理自知乎我的一次回答：
我的观点，只写说明性注释，不写功能性注释。也就是说，注释Why，而不是How和What。
类和函数多写文档注释，多少行无所谓，写在最前面，只要你是注释的Why。
函数内部，尽量少写注释。如果你的代码需要写注释来说明他的功能，那么这段代码就需要重构，最简单的方法，最简单的方法：提取函数。这样的好处是，函数名就是注释。一个错误的观点就是 注释是给人看的，程序是给电脑看的。其实，程序是给人的，凑巧的是，它居然可以在电脑里运行。
《》一书写道：
每当感觉需要以注释来说明点什么的时候，我们就把需要说明的东西写进一个独立函数中，并以其用途（而非实现手法）命名。
每次我给别人讲解「选择排序」、「插入排序时」，他们都觉得太难了，而且几乎每本数据结构教科书都是写了一堆代码和注释，这丝毫没有降低这个算法的难度。
如果不写注释，而写成函数呢？
伪代码：
array_ordered = []loop_all_element(array, function(i){ el = select(array[i+1, array.length]) push(array_ordered, el) ......}) - 构建一个有序数组，初始为空，（PS：空数组肯定是有序的）
- 循环整个数组，进行如下操作：
- 从数组剩下的元素里面选择最小的（或最大的）
- 将最小元素放在有序数组的最后面（或者最前面）
不用我多解释，你一眼就知道（看我加粗的字），这是选择排序。
插入排序呢？大同小异，我就不详细写了。
所以，文档注释，多少无所谓。函数内、类内注释，能不写，就不写。
相关阅读：