MyException - 我的异常网
当前位置:我的异常网» 编程 » 老生常谈:注释如何写

老生常谈:注释如何写

www.myexceptions.net  网友分享于:2013-04-10  浏览:7次
老生常谈:注释怎么写?

整理自知乎上我的一次回答。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
函数外注释,说的不错

文章评论

软件开发程序错误异常ExceptionCopyright © 2009-2015 MyException 版权所有