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.)
Re:What does this code do?
by blankity_blank on Wednesday July 21, 2010 @04:00PM
(#1536355)
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.
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?