整理自知乎上我的一次回答。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)
......
})
- 构建一个有序数组,初始为空,(ps:空集都是有序集)。
- 循环整个数组,进行如下操作:
- 从数组剩下的元素里面选择最小的(或最大的)
- 将最小元素放在有序数组的最后面(或者最前面)
插入排序呢?大同小异,我就不详细写了。
所以,文档注释,多少无所谓。函数内、类内注释,能不写,就不写。
相关阅读:千万要避免的五种程序注释方式