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


当前回答

在大学的一次家庭作业中,一位老师特别坚决地要求我们注释代码:

//I wonder if she actually reads these.

当作业被返回时,在注释“是的,我愿意”旁边用红笔写着

其他回答

//Not a bug, parameter position can change..., if you think this is wrong, you are in fact wrong.

这是我曾经必须支持的实际代码。在努力理解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...";
    }
}

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

在drivers/net/sunhme.c (Linux内核)中:

/* Welcome to Sun Microsystems, can I take your order please? */
if(!hp->happy_flags & HFLAG_FENABLE)
        return happy_meal_bb_write(hp, tregs, reg, value);

/* Would you like fries with that? */
hme_write32(hp, &tregs->frame,
            (FRAME_WRITE | (hp->paddr << 23) |
             ((reg & 0xff) << 18) | (value & 0xffff)));
while(!(hme_read32(hp, &tregs->frame) & 0x10000) && --tries)
        udelay(20);

/* Anything else? */
if(!tries)
        printk(KERN_ERR "happy meal: Aieee, transceiver MIF write bolixed\n");

/* Fifty-two cents is your change, have a nice day. */
// Jay knows what's going on here, but will he remember in a year? Not very likely, this code sucks, but it works so do not change it.

这条评论被贴在一个巨大的“如果”区块上…哦,它操纵一个对象数组的对象数组的对象数组的字符串对象数组,可以是字符串或数字,取决于至少3个因素…(是的,我必须调试这段代码并更改它,我写了注释,但我没有写原始代码)。;)

这不是严格意义上的评论,但是…

那是20世纪90年代中期,我正在进行一次大的迁移:小软件供应商,大客户,压力很大。我们有很多转移门柱的东西;这个项目很难控制。我是关键的开发人员,但对系统还不熟悉,而另一个开发人员是供应商的所有者/创始人。

在几个月没有按时完成任务,也没有让客户满意之后,公司的所有者/创始人找来了另一名远程工作的开发人员。(我可以大胆地说,新开发人员的技能和经验都不如我。)

好吧,这个新人对我已经做过的代码做了一些更改,然后一两个月后我又回到了代码的同一区域,其中有一些我以前没有见过的变量。他的名字叫StupidMark。

伙计,这是不对的。我的意思是,有团队合作方面的考虑,但是:在这个环境中,变量名可能会出现在运行时错误消息中。我只是说说而已。

在我看来,那个新人的代码并没有让我们更接近可交付的产品,这让侮辱变得更伤人了。