这段程序是做什么的？

在Java 2010大会上，一位发言人给我们展示了几段简短的代码，并且问我们每段代码都是做什么用的。代码写的很明了，但没有提供上下文的注解。下面的就是这最后一段代码：

 

def what( x, n ):

     if n < 0 :

         n = - n

         x = 1.0 / x

     z = 1.0

     while n > 0 :

         if n % 2 = = 1 :

             z * = x

         x * = x

         n / = 2

     return z

这个测试是在这天快要结束时进行的，我有些累了。我说不出这段代码是干什么用的。可后来我发现自己处于很尴尬的境地，其实这段代码所实现的算法我是十分熟悉的。我曾经写过相同的代码，而且还写在了博客里。

这个事件使我改变了对“自我注解”程序的理解。没有上下文的提示，你很难理解一段代码是干什么用的，即使是很小一段。

有意义的变量名称和函数名能给理解程序带来很大帮助，但一句简单的注释带来的帮助更大。我们不需要那些冗余的注释，就像解释这行代码x = 1.0 / x 是取一个数的倒数，我们要的注释是能解释这段代码是来解决什么问题的。

这还有个例子，你认为这段代码是干什么的？

uint what()

{

     m_z = 36969 * (m_z & 65535) + (m_z >> 16);

     m_w = 18000 * (m_w & 65535) + (m_w >> 16);

     return (m_z << 16) + (m_w & 65535);

}

很明显这段代码是处理底层问题的 — 它只有一些操作 — 但我们完全不知道它是干什么的。

在继续往下读之前你最好尽力思考一下这段代码。如果你放弃了，那我告诉你，上面的第一段代码是来自这里的，第二段代码是来自这里的。

在通常我们的面对面交流中，有很多的信息是来自口头表达之外的。我们通常会认为我们的语言表达是最重要的，但是我们的语调，面部表情，肢体语言等传递了更多的信息。程序源代码跟这些很相似，我们通常会在里面隐含着大量的其它信息。

假设你的同事Sam请你帮他审查一下他的代码。工作中发生这种情况一般你能得到大量的上下文语境帮助；它们并不是网上的某个随机的代码片段。更特殊 的是，你还对Sam所工作的项目有相当的了解。你知道Sam为什么希望你帮他看一下他的代码。也许他想炫耀一下他引以为豪的杰作，或者他希望你帮他找出一 个bug。你在看他的代码之前已经有了相当的了解。

但如果你是个接手人。Sam不幸被车撞了，你被要求在Sam出院之前维护他写的代码。你很可能会向他的同事抱怨，说他写的代码是如此的糟糕，但他的同事却不理解你为什么要这样说。他的同事会认为Sam的代码非常的清晰易懂。

再假设你是Sam接手人，而且在世界的另一端。你不能跟他的同事很好的交流，你只知道很少的上下文语境。在痛苦的折磨后，你把你修改的程序发回Sam的公司。你把你的程序注释的非常充分，但Sam的同事却抱怨你的代码乱极了，你并没把问题真正的解决。

共事共识比源代码注释更有价值。所以说替换一个程序员的代价是巨大的，即使是他走时留下的是注释很好的程序。

 

翻译来源：外刊IT评论

 

：)

评论

17 楼 nkadun 2010-08-21  

一个团队内的成员有共同的代码习惯是最主要的，然后就是让保证团队成员的稳定，代码是死的，人是活的……

16 楼 NanguoCoffee 2010-08-20  

这种代码必须有注释呀。 只需简单的描述会产生什么结果就行了，不需要对算法进行注释，最后给出几个例子来说明该方法的结果。 Apache common中的源码的注释就不错。

15 楼 dukai1008 2010-08-17  

不知道JE上什么时候出来了一群牲畜，动不动就投隐藏！觉得这样很有意思啊！

好待人家也辛辛苦苦的写出来，为什么JE自己就可以打广告，人家就不行？你去看看，那个文章里面有没广告，气愤！

何况人家就是简单的贴个链接而已，那群手痒的牲畜不通人性也难怪了！

14 楼 JustDoNow 2010-08-13  

这是java？

13 楼 ge_cc 2010-08-13  

what...

12 楼 t42dw 2010-08-13  

我想我OUT拉，我怎么觉得那不是java代码呢？

11 楼 王者之剑 2010-08-12  

hoby_yyy 写道

王者之剑 写道

除了函数名叫what以外，没有什么不妥吧

你那我贴的那段代码， 换几个 x  和  n 的值跑一下 就知道有没有问题。

没有问题阿，你的函数名就叫what，跑出来what就是what。

如果你叫add或者pow，才可能跑出问题来。

10 楼 parabellum_sky 2010-08-12  

跑完之后没有问题啊～～

9 楼 hoby_yyy 2010-08-12  

王者之剑 写道

除了函数名叫what以外，没有什么不妥吧

你那我贴的那段代码， 换几个 x  和  n 的值跑一下 就知道有没有问题。

8 楼 王者之剑 2010-08-12  

除了函数名叫what以外，没有什么不妥吧

7 楼 cyberpeng 2010-08-12  

lc4ever 写道

X的N次方,指数运算,考虑到了N为负的情况

犀利

6 楼 hoby_yyy 2010-08-12  

第一段代码有问题吧。
public static void main(String[] args) {
// TODO Auto-generated method stub
double x;
double n;
double z;
n=8;
x=2;

if(n<0){
n=-n;
x=1.0/x;

}

z=1.0;

while(n>0){

if(n%2==1){
z*=x;
}
x*=x;
n/=2;
}
System.out.println(z);

}

5 楼 lesorb 2010-08-12  

python

4 楼 stupidmxx 2010-08-12  

話說根據原文，這是在SciPy大會上的發言啊。。。如果都是搞數學的，寫出這樣的代碼來也不出奇

3 楼 stupidmxx 2010-08-12  

第一個是計算x的n次方的“快速”算法吧，第二個感覺有點像算hash的

2 楼 liujunsong 2010-08-12  

我觉得吧,不管干啥,都别搞成猜迷语.
文档这东西吧,该写的还是不能省的;写太多没人看也是白扯.

1 楼 lc4ever 2010-08-12  

X的N次方,指数运算,考虑到了N为负的情况