你遇到过的源代码中最好的注释是什么?


当前回答

几年前,我在一个没有单元测试可言的大型代码库中工作。

代码中隐藏了一个执行一些日历计算的方法。它有点坏了,由于一些不幸的情况,不得不以一种非常笨拙的方式处理夏令时。

我们不得不修了几次,每一次,我们都会在几个月后发现一些东西坏了。

在花了一整天的时间修复和分析之后,我把代码放到了源代码控制中,并附上了这样的评论:

// this code was written after a version trying to do {this} failed because of {reason},
// previously we were doing {this} which failed because of {reason}. This is 
// now written {this} way so that {lots of reasons here}. If you want to touch
// this code, please make sure that it produces the right answers when tested with:
//
// {some sort of unit test}

最终,我的团队被外包了。有时我想知道这段代码发生了什么:)

其他回答

这是我曾经必须支持的实际代码。在努力理解AstaSaysGooGoo和AstaSaysGaaGaa(在那里有更多的astaTempVars被声明和使用)的逻辑之后,我准备放弃。我终于抬头看到了“@author”的评论,整件事开始有意义了。

/*

* @author Andrew Asta
*/
public class AstaClass{

    private String astaVar1;    
    private String astaVar2;    
    private String astaVar3;    
    private String astaVar4;    
    private String astaVar5;    
    private String astaVar6;    
    private String astaVar7;    
    private String astaVar8;    
    private String astaVar9;    
    private String astaVar10;   

    public void AstaSaysGetData(){
        //JDBC statement to populate astavars 1 through 10
        //...
        String astaSqlStatment = "Select astaCol1, astaCol2, astaCol3... From AstaTable Where...";
        //..
        //...
    }

    //Perform data manipulation on astavars...
    public void AstaSaysGaaGaa(){
          [removed for sake of brevity]
    }


    //Perform more data manipulation on astavars...
    public void AstaSaysGooGoO(){
        [removed for sake of brevity]
    }

    public void AstaSaysPersist(){      
        //JDBC statement to save astavars to DB 
        String astaSqlStatment = "Update AstaTable set astaCol1 = @astaVar1
                                                  , set astaCol2 = @astaVar2
                                                  , set astaCol3 = astaCol3... 
                                                  Where...";
    }
}

另外,我更改了实际作者的真实姓名,以避免我陷入任何纠纷等等…

Repeat
    ...
Until (JesusChristsReturn) ' Not sure
try {

} finally { // should never happen 

}
    /* Mark: If there's one thing you learn from this code, it is this...
   Never, ever fly Air France.  Their customer service is absolutely
   the worst.  I've never heard the words "That's not my problem" as 
   many times as I have from their staff -- It should, without doubt
   be their corporate motto if it isn't already.  Don't bother giving 
   them business because you're just a pain in their side and they
   will be sure to let you know the first time you speak to them.

   If you ever want to make me happy just tell me that you, too, will
   never fly Air France again either (in spite of their excellent
   cuisine). 

   Update by oej: The merger with KLM has transferred this
   behaviour to KLM as well. 
   Don't bother giving them business either...

   Only if you want to travel randomly without luggage, you
   might pick either of them.
   */

来自一个显然在看巨蟒剧团的小伙子:

> //现在,for something完全 > // different: 类theLarch {