4 ms·
I'm sad to see that the one line of code, with its magic number and comparatively inscrutible contents, is entirely undocumented. Please, if doing things like t
by chrismorgan 13y ago
I'm sad to see that the one line of code, with its magic number and comparatively inscrutible contents, is entirely undocumented. Please, if doing things like that: a good commit message is necessary but not sufficient. (Yes, `git blame` exists, but you're not so likely to use it as a comment in the code.) A blog post is handy but not sufficient. A good inline comment is invaluable when returning to the code later if the situation changes, as it typically will in time for such precise, empirically derived performance tweaks.
// This single line boosts performance by a factor of around 2 on GCC.
// The optimal lookahead distance i+3 was chosen by experimentation.
// See http://www.naftaliharris.com/blog/2x-speedup-with-one-line-of-code/
- naftaliharris 13y agoYeah, you're right: had I not written the code myself, it would not have been clear to me what that special line did or why i+3 without documentation. Your proposed comment describes it nicely; I've added it verbatim: https://github.com/naftaliharris/lazysort/commit/a56f30adef716f3076855f915abba06bb2cdb64c https://github.com/naftaliharris/lazysort/commit/a56f30adef7...
- thejosh 13y agoReferencing a URL, especially a blog, that could die anytime in documentation isn't good.
- chrismorgan 13y agoI agree with your general sentiment and was initially inclined to make the comment more verbose and not include the URL; I would certainly not be content with just a URL. Still, in this case I would consider it a fair compromise, primarily because the inclusion of the URL is non-essential but value-adding. That is, it explains more, but the two important points—the purpose of the code and the reason for the number 3—are captured by the lines above, but the blog post adds more information which could potentially be of use later. Furthermore, the author of the code is the author of the blog post, which increases the probability of its survival.
- chris_wot 13y agoI'd it the detailed explanation into the commit message. Or you could add it to README or make a file NOTES and explain it there.
- raverbashing 13y agoNo, please, don't Not like this. Yes, the +3 deserves an explanation (but something better than "because of experimentation" - my guess is because it's big enough to get the next cache line and small enough to not get something that won't be needed) And I find it funny when people on HN are shibeing __builtin_prefetch like "wow, I just heard about caches and prefetching data how amazing"
- chris_wot 13y agoThat last line seems a little snarky. Not everyone knows built in prefetch directives in gcc.