I once worked for a software house that had real standards, real code walk-throughs, and real quality control. Standards were enforced vigorously through automation and peer review. Those standards included precise variable naming conventions.

At the time, I hated it because I thought it cramped my style.

Since then, I have worked in many shops with no standards at all and most of the crap I've had to maintain looked just like OP's examples. Probably written by someone who didn't like his style cramped.

Funny how it sometimes takes years to understand that which once made no sense.

Reminded me of a good quote:

“When I was a boy of 14, my father was so ignorant I could hardly stand to have the old man around. But when I got to be 21, I was astonished at how much the old man had learned in seven years.” - Mark Twain

Note: Spoiler alert.

The author says, "Meaningful variable and function names would have helped, but..." and I don't really see why he needed the "but." The first function can be renamed "get_exponent(base, exponent)" and the second, "get_random_integer()", and that's the end of it. What more comments would really be appropriate?

I think a comment specifying the name of the algorithm would be great if you want to dig deeper when the function isn't working.

That's a good point. The author said, "... a comment explaining the problem the code is trying to solve [would have helped]," which is what threw me--that's what the function name is for!

What am I doing rewriting pow?

Specifically, naming the algorithm would be good, but the comment should also say why. //This is called by the frobbinator module where preconditions A and B are met, which makes this more efficient.

I came here to post exactly that. He says 'well this makes me re-think self-documenting code', when in reality writing readable code would have provided all of the documentation necessary. I don't get his point.

For 10 lines of code, a meaningful function name might be enough documentation. But suppose instead of a 10-line function the same code were 10 lines inside a 100-line function. Then you'd need a comment. (It would be better to break it out as its own function, but suppose it were not so easy to factor out.)

This actually further highlights the issue of code that is "self-documenting" to one person but not the other. "get_exponent" would confuse the heck out of me (is it just supposed to return the second argument unchanged?), but I would have no trouble with "pow" or "exp". But a comment that says "raise x to the power of n; n must be an int" leaves much less room for interpretation.

I fear for the person who has to decode the second one with a name like "srng_get()" however.

  if n < 0:
        n = -n
        x = 1.0 / x

Dead giveaway.

Dead giveaway for developers who know math, you mean.

Er, it's just exponentiation with a (possibly negative) integer exponent. High-school-level arithmetic, maybe junior high.

If your peers don't know this, you're in trouble.

Who else should be reading procedural code written in a compiled language?

Well, sure, but it doesn't always work out that way.

The reason to document WHAT code does, is so a reader can parse it faster. The most common ignorant reader is yourself, several weeks/months later.

Method names are good, but some clue about the approach is helpful too, which the method name would probably not include.

The article asks the question "what does this code do" but never reveals the answer. The first algorithm is fast exponentiation.

He provides links for both functions, here: http://www.johndcook.com/blog/2008/12/10/fast-exponentiation... and here: http://www.codeproject.com/KB/recipes/SimpleRNG.aspx

Ah, I missed that, my bad.