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


当前回答

首先,在一个大对象的更新的开始:

/*General note to all who tread in the <ObjectName>() code...
 * The SetOriginals() method from the BaseEntity class should be called (and only called) right after the Get() method
 * call as seen above.  Calling the SetOriginals method elsewhere will result in bugs and all kinds of other nasty suprises.
 */

然后在大约200行逻辑之后更新对象:

//Attempt to explain this confusing mess of code:
//First time you save an actual absence this is what happens:
//0. The first save saves to the <TableName> table (among other things). (Fig. A)
//1. The <CalculationMethod> method is called next which inserts to the <OtherTableName> table. 
//(This is the table that keeps track of credits to the case.) (Fig. B)
//2. So then you have to call <UpdateCalculations> to move the <TableName> records to the <ThirdTableName> table. (Fig. C)
//3. Then you go back and run calculations since you have the debits table (<ThirdTableName>) populated. (Fig D.)
//4. Then a final save to save the calculations back to the case. (Fig. E)
//Yeah, I know what you're thinking:  this sucks. 10/01/07 XXX

开发商是对的……这太糟糕了!

其他回答

来自嵌入式系统中的电池监测模块:

// batmon.c drives the rastamobile

我们的团队,就在今晚,发布了一个新版本的CSS文件,删除了一个文件的注释,该文件的结构是这样的:

@charset "UTF-8";
/* Who knew comments here could COMPLETELY ruin our page in Safari? */
body {
        /* Really important stuff here */
        /* Of course, comment or not, this will all get ignored by Safari because 
           its the first rule after the comments which break everything.
           see http://www.w3.org/International/questions/qa-css-charset for the exact details!
        */
}

有趣的是,在网上你会发现人们的解决方案是输入一个虚假的元素作为字符集语句下面的第一条规则,然后被忽略,照常进行…

发人深省的问题:该把不评论的评论放在哪里?

旁注:我知道这是不需要的,因为头,元规则等。不幸的是,我们需要它作为一个catch all:(

def format_ticket_content(text, recursive = true)
  if text.is_a?(TicketNote)
    note = text
    text = note.content
  else
    note = nil
  end

  ## Safety pig has arrived!
  text = h(text)
  ##                               _
  ##  _._ _..._ .-',     _.._(`))
  ## '-. `     '  /-._.-'    ',/
  ##    )         \            '.
  ##   / _    _    |             \
  ##  |  a    a    /              |
  ##  \   .-.                     ;  
  ##   '-('' ).-'       ,'       ;
  ##      '-;           |      .'
  ##         \           \    /
  ##         | 7  .__  _.-\   \
  ##         | |  |  ``/  /`  /
  ##        /,_|  |   /,_/   /
  ##           /,_/      '`-'
  ## 

我在查看TVNZ网站早期迭代的HTML源代码时发现了这个宝藏(如果你在家玩的话,从571行开始):

<!-- Hopfully we can do this otherwise the nav is going to be pretty plain and Hong will go postal. -->