5 ms·

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 f

by mcantor 16y ago

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?

jpablo 16y ago
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.
- mcantor 16y ago
  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!
- fragmede 16y ago
  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.
enjo 16y ago
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.
- johndcook 16y ago
  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.)
Groxx 16y ago
I fear for the person who has to decode the second one with a name like "srng_get()" however.
blankity_blank 16y ago
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.

by mcantor 16y ago

jpablo 16y ago

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.

mcantor 16y ago
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!
fragmede 16y ago
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.

enjo 16y ago

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.

johndcook 16y ago
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.)

Groxx 16y ago

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

blankity_blank 16y ago

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.