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


当前回答

public GetRandomNumber()
{
    // Chosen by a fairly rolen dice
    return 12;
}

其他回答

我曾经见过这个:

//this used to be a comment
// Keep prozac ready if things get ugly!

我刚刚完成了一个日志框架(使用Trace,为什么没有这样的存在我不知道)。我做了一个继承自TraceListener的方便基类。它覆盖了所有的TraceListener方法,并将它们路由到一个方法中——因此有很多文档注释:

// TODO: Need some codemonkey to doc comment this class.

Re eating one's own dogfood: We have the same term in our workplace (granted, only because I introduced it). My code is peppered with comments that say "TODO" and indicate something that ought to be done eventually, but a comment saying "DOGFOOD" (both keywords are always at the beginning of the comment, in all caps) means something that must be done before this program can be used even internally. It's a handy thing to search for, as the word "dogfood" is never going to appear in a quoted string - if it does, I can always just say "dog-food" or something - so even a case-insensitive search will come up with the right results.

Regarding zeroing the accumulator: I've done exactly the same thing when programming an Intel 80x86 (I started on the 8086 and moved up from there into the modern Pentiums). XORing a register with itself is the quickest and tightest way to clear it. Using "MOV AX,0" requires three bytes (opcode and two bytes of literal 16-bit zero), whereas "XOR AX,AX" is only two; it's even more noticeable with the 386-and-higher extended registers, where "MOV EAX,0" requires five bytes (four bytes of 32-bit zero). My C/C++ compiler always zeroes registers this way, so I'd assume it's still the best way (although I haven't studied opcode timing tables in ages, and probably both XOR reg,reg and MOV reg,imm take one clock).

我在我发布的WordPress模板中发布了这个“许可声明”。不管怎样,我觉得这很有趣。

/* The License:
You (from this point on referred to as The You) are hereby 
granted by me (from this point on referred to as The Me) 
license to knock yourself silly with this template. 
By using this template The You implicitly accepts this 
license and pledges solemnly to never claim creative 
ownership of any graphics, code, concepts, eggs, bacon, ideas, 
colors, shapes, hypertext-transfer protocols or other conduits 
of the visual splendor thatis this template. 

The Me, in turn, pledges equally solemnly to be far too 
lazy to ever check up on you, so if you do manage to pull 
some chicks The Me won't have a cow. 
However The Me would be sorely disappointed if The You 
were to try and sell or distribute this work without 
acknowledging The Me. Seriously. The Me will come down on 
The You like a large quantitiy of hard and heavy objects 
that in large quantities may be harmful and possibly even 
lethal to The You; So don't even think about it, The Buster.
*/