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


当前回答

下面是我在不同时间放入代码中的一些代码。有些不是严格意义上的评论,但它们是相同的概念。

在一个跨平台项目中,只需要在一个平台上执行一些特殊代码:

//If defined, will include all the Windows-specific code.
#define LOSE

#ifdef LOSE
#include <windows.h> //WIN32. Duh.
#endif


---------------------------------------------------


//Stolen from other_project_name.cpp


---------------------------------------------------


/*
 * These comments have been lifted from propagate() and, though they no longer apply to the code, they may still be of value somewhere. Original tabbing and structural elements have been preserved.
 */
    //CAUTION: This has a major Bobby Tables risk. Even if a rulebuilder is used, there's still the risk of something getting corrupted in the database itself.
    //Reading text from anywhere and simply slotting it into an SQL statement is a major security risk. (With thanks to xkcd for the name "Bobby Tables".)
    //Requirement: Eliminate one Bobby Tables by changing [redacted] to be not just straight SQL.
[lots more comments that are not as funny]
/*
 * End of lifted comments. There should not be any executable code between these markers.
 */


---------------------------------------------------


        /*
        Okay. It's unrecognized. Why is this a fatal error? It's actually very closely akin to the miswart of botched #includes being a fatal. When writing a C/C++
        program, you need your headers, and if you don't have one, chances are there'll be a million cascaded errors; so by making "unable to open asdf.h" a fatal,
        the compiler suppresses all those errors about undefined symbols and potentially misspelled type names.
        */


---------------------------------------------------


    //If someone tries to import 'id' as a field name, it won't work. (We already have our own id.) But I think the probability is so low that I can afford to be funny.
    if (!stricmp(ptr,"id")) {warn(0,"Import","","'id' is a reserved word and cannot be used as a column name. (Try 'ego' or 'superego'.)"); return;}


---------------------------------------------------


//Need a place to squirrel away SQL statements somewhere
char *uts[1024]; //Unified Temporary Storage. (Why? Because I said so.)
int nuts=0; //What is it that squirrels keep? Ha!
int utsid[sizeof uts/sizeof *uts];


---------------------------------------------------


        /**************************************\
         * NOTE: This sets tilde.action. If a *
         * tilde header does not exist in the *
         * import file (not the _content_, if *
         * the entire column isn't there), it *
         * will duplicate down through all of *
         * the rows. This is fine for ~id, as *
         * that will never be changed; and if *
         * ~Quantity is blank, that throws an *
         * error in 'Add'. With ~Action, I am *
         * not so certain. I THINK it'd be OK *
         * to dup-down most of the time... if *
         * the user only ever imports Adds or *
         * Revises, but never both at once in *
         * a single import. So for safety, to *
         * allow a blank ~Action to revise OR *
         * add, I'm breaking the check out to *
         * a new variable - the curaction. In *
         * most cases, it won't be needed, so *
         * it's a waste; but it isn't like it *
         * has to copy the entire tilde.*, so *
         * it's only a small waste. So it can *
         * waste a register... big deal. OK ! *
        \**************************************/


---------------------------------------------------


            //if (!response) // we're going to crash
            //if (!items) // we're going to crash
            //TODO: Don't crash


---------------------------------------------------

我的很多评论都隐晦地提到了电影或音乐剧,但如果你不了解这部剧,它们就不会那么有趣了。

其他回答

许多年前,我接受了这份工作,为一个真正运行的项目提供支持 在Z80上的时间和组装(有其他方法做Z80吗??) 不管怎样,原作者是一个叫摩西的尼日利亚人。也许我应该 就此止步。 不管怎样,代码中到处都是这样的:

XRA A    ;MT

我花了好长时间才弄明白这是什么。指令本身没有其他作用 比清除蓄能器。这是一种狡猾的方法,尽管我不确定是否有 不管是不是优势。你可以这样做:

LDA 0

但也许

XRA A

节省一个字节之类的。is所做的是排他的或者是累加器本身。 当然,结果总是零。

回到MT -空(明白吗?)

这是我遇到的最好的。

有人抱怨说,“最好的”评论会带来最糟糕的评论。恕我直言,他们更有趣,所以“更好”,但这是我读过的最好的评论:

/*
Major subtleties ahead:  Most hash schemes depend on having a "good" hash
function, in the sense of simulating randomness.  Python doesn't:  its most
important hash functions (for strings and ints) are very regular in common
cases:

>>> map(hash, (0, 1, 2, 3))
[0, 1, 2, 3]
>>> map(hash, ("namea", "nameb", "namec", "named"))
[-1658398457, -1658398460, -1658398459, -1658398462]
>>>

This isn't necessarily bad!  To the contrary, in a table of size 2**i, taking
the low-order i bits as the initial table index is extremely fast, and there
are no collisions at all for dicts indexed by a contiguous range of ints.
The same is approximately true when keys are "consecutive" strings.  So this
gives better-than-random behavior in common cases, and that's very desirable.

OTOH, when collisions occur, the tendency to fill contiguous slices of the
hash table makes a good collision resolution strategy crucial.  Taking only
the last i bits of the hash code is also vulnerable:  for example, consider
[i << 16 for i in range(20000)] as a set of keys.  Since ints are their own
hash codes, and this fits in a dict of size 2**15, the last 15 bits of every
hash code are all 0:  they *all* map to the same table index.

But catering to unusual cases should not slow the usual ones, so we just take
the last i bits anyway.  It's up to collision resolution to do the rest.  If
we *usually* find the key we're looking for on the first try (and, it turns
out, we usually do -- the table load factor is kept under 2/3, so the odds
are solidly in our favor), then it makes best sense to keep the initial index
computation dirt cheap.

The first half of collision resolution is to visit table indices via this
recurrence:

    j = ((5*j) + 1) mod 2**i

For any initial j in range(2**i), repeating that 2**i times generates each
int in range(2**i) exactly once (see any text on random-number generation for
proof).  By itself, this doesn't help much:  like linear probing (setting
j += 1, or j -= 1, on each loop trip), it scans the table entries in a fixed
order.  This would be bad, except that's not the only thing we do, and it's
actually *good* in the common cases where hash keys are consecutive.  In an
example that's really too small to make this entirely clear, for a table of
size 2**3 the order of indices is:

    0 -> 1 -> 6 -> 7 -> 4 -> 5 -> 2 -> 3 -> 0 [and here it's repeating]

If two things come in at index 5, the first place we look after is index 2,
not 6, so if another comes in at index 6 the collision at 5 didn't hurt it.
Linear probing is deadly in this case because there the fixed probe order
is the *same* as the order consecutive keys are likely to arrive.  But it's
extremely unlikely hash codes will follow a 5*j+1 recurrence by accident,
and certain that consecutive hash codes do not.

The other half of the strategy is to get the other bits of the hash code
into play.  This is done by initializing a (unsigned) vrbl "perturb" to the
full hash code, and changing the recurrence to:

    j = (5*j) + 1 + perturb;
    perturb >>= PERTURB_SHIFT;
    use j % 2**i as the next table index;

Now the probe sequence depends (eventually) on every bit in the hash code,
and the pseudo-scrambling property of recurring on 5*j+1 is more valuable,
because it quickly magnifies small differences in the bits that didn't affect
the initial index.  Note that because perturb is unsigned, if the recurrence
is executed often enough perturb eventually becomes and remains 0.  At that
point (very rarely reached) the recurrence is on (just) 5*j+1 again, and
that's certain to find an empty slot eventually (since it generates every int
in range(2**i), and we make sure there's always at least one empty slot).

Selecting a good value for PERTURB_SHIFT is a balancing act.  You want it
small so that the high bits of the hash code continue to affect the probe
sequence across iterations; but you want it large so that in really bad cases
the high-order hash bits have an effect on early iterations.  5 was "the
best" in minimizing total collisions across experiments Tim Peters ran (on
both normal and pathological cases), but 4 and 6 weren't significantly worse.

Historical:  Reimer Behrends contributed the idea of using a polynomial-based
approach, using repeated multiplication by x in GF(2**n) where an irreducible
polynomial for each table size was chosen such that x was a primitive root.
Christian Tismer later extended that to use division by x instead, as an
efficient way to get the high bits of the hash code into play.  This scheme
also gave excellent collision statistics, but was more expensive:  two
if-tests were required inside the loop; computing "the next" index took about
the same number of operations but without as much potential parallelism
(e.g., computing 5*j can go on at the same time as computing 1+perturb in the
above, and then shifting perturb can be done while the table index is being
masked); and the dictobject struct required a member to hold the table's
polynomial.  In Tim's experiments the current scheme ran faster, produced
equally good collision statistics, needed less code & used less memory.

Theoretical Python 2.5 headache:  hash codes are only C "long", but
sizeof(Py_ssize_t) > sizeof(long) may be possible.  In that case, and if a
dict is genuinely huge, then only the slots directly reachable via indexing
by a C long can be the first slot in a probe sequence.  The probe sequence
will still eventually reach every slot in the table, but the collision rate
on initial probes may be much higher than this scheme was designed for.
Getting a hash code as fat as Py_ssize_t is the only real cure.  But in
practice, this probably won't make a lick of difference for many years (at
which point everyone will have terabytes of RAM on 64-bit boxes).
*/
int MyFunction()
{
    // There once was a man named Dave
    int Result = 0;

    // Whose code just wouldn't behave
    MyObject *Ptr = new MyObject();

    // He left to go to a meetin'
    Result = Ptr->DoSomething();

    // And left his memory a leakin'
    return Result;
}

c++怎么样

我刚刚注意到自己在写这个

// not brilliant solution, but fair enough heh.

.class {border:1px solid gold;} /*我可怜这个傻瓜*/