老生常谈:注释怎么写?

justjavac 发布于 2013/04/07 13:26
阅读 886
收藏 19

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

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

所以, 文档注释,多少无所谓。函数内、类内注释,能不写,就不写
加载中
0
七液
七液

其实应该存在一种代码和注释相分离的源码结构或者说是自动分割和合并的结构。

比如使用XML来进行注释,IDE打开源码的时候,IDE自动把注释软连接到源码里面去,如果需要查看注释的话直接点进去就可以看到非常详细的注释信息,包括如何设计,为什么这么做,而且源码编译和发布的时候也就不需要这么多没用的注释信息了(甚至有些人发布源代码的时候注释都删除掉,自己保留有注释的)其实简单的显示注释给出详细注释请参见no.xxxx.xx号文档.这样效果最好。只是大家习惯了文本,这种老式的做法是当初没有自动化的ide下的妥协产物,现在的编译,管理技术这么先进没有必要在使用这种老式的源码存储方案了。至少我个人觉得应该要分离

justjavac
justjavac
这就是“文档注释”
0
写代码有注释
写代码有注释
这个要看,你写的这个注释是给谁看的
0
中山野鬼
中山野鬼

引用来自“戊己杏黄旗”的答案

这个要看,你写的这个注释是给谁看的
哈,肯定给看代码的人看,绝不会给项目经理看。。。
0
温习江湖
温习江湖
受教了,对于现在自动化程度很高的编程工具,长变量名也就是3、4个按键的事
返回顶部
顶部