Update the Performance Tip doc

[Sisyphuss]

Current performance tips (TIPS) is not very pedagogical. So I rewrite a part of TIPS to make it more understandable. The change includes rewriting the motivation (at the beginning), adding section "why Julia can be fast", rewrite section "avoid global variables" as "be cautious to the use of global variables, especially in a loop". Numerous examples and intuitions are provided.

[tkelman]

Need to remove the trailing whitespace here, otherwise Travis will fail.

[johnmyleswhite]

I think we should not include this paragraph.

[iamed2]

I agree. Seems unhelpful, accusatory, and discouraging.

[stevengj]

It would be more helpful if you did not mix constructive improvements and examples with rants, gripes, and snark.

[stevengj]

Inflammatory and inaccurate; there are many optimization techniques employed by Julia and LLVM. Of course, type inference is a crucial one — no performance-critical code in any language can be compiled to efficient machine instructions if types cannot be detected and some point prior to final execution.

[timholy]

If you're curious, @Sisyphuss, check out #3440. It's worth noting that some boxes not checked are already largely in place.

[Sisyphuss]

... Someone can tell me why I didn't pass the appveyor check? Is it because I edited it in LibreOffice ant then copy-paste it?

The "Detail" says that "build has been cancelled by user." But I don't remember I have done anything about it.

[tkelman]

Someone probably manually cancelled the build. Since this is documentation-only there are no platform differences here and it's not worth wasting 45 minutes of queue time to run on AppVeyor. That's why we ask contributors to add [av skip] somewhere in the commit message for doc-only commits, though it doesn't look like I've written that down in CONTRIBUTING.md yet.

[Sisyphuss]

So appveyor is to check whether it can run in different platform (Windows, Mac OS, Linux, etc.)? So there isn't any fault on my side?

By the way, if I'd like to add av skip, should I include the blanket []?

[tkelman]

So appveyor is to check whether it can run in different platform (Windows, Mac OS, Linux, etc.)?

AppVeyor is for Windows. Travis is for Linux. Travis can test on Mac OS as well but we currently have that disabled because it was timing out frequently.

So there isn't any fault on my side?

Correct.

By the way, if I'd like to add av skip, should I include the blanket []?

It does need the surrounding brackets, yes. [av skip] can be anywhere in the commit message though.

[tkelman]

The tone in the additions here is much better than it initially was, the grammar could still use a little bit of revision though.

[KristofferC]

I agree, this is a much more pleasant read than before the changes.

[timholy]

Agreed. With regards to the grammar, I think a native speaker should tackle that; it's not efficient to expect a non-native speaker to produce perfect prose. Either we could merge this as is and then polish it, or someone could submit a PR against his branch.

[Sisyphuss]

Please feel free to correct my linguistic faults. I am open to listen to different voices. This will also help me to better master the language of Shakespeare. And I will also prove that I live up to your expectations.

[ViralBShah]

Can you squash these commits? I don't mind doing a cleanup on this branch and merging it.

[JeffBezanson]

I think this text is just too long; I prefer the tips to be short and to the point.

[tkelman]

The examples are nice to have here, and if more elaboration on this leads to more people figuring out the common pitfalls on their own without having to go to the mailing list (or giving up before that) then it's a good thing IMO.

[timholy]

If "performance tips" isn't the right place, how about putting it in the FAQ and inserting a link from here? Overall, I'd say "too much documentation" is not high on the list of julia's problems.

[Sisyphuss]

I'm sorry for my lateness. I was too occupied.

Concerning the "squash", I haven't figured out how to do that. My local Julia build's source code is downloaded via the official repo, while this doc improvement obviously has nothing to do with my local build. Therefore, I do not know how to do rebase as various git help docs suggest.

By the way, does the close of this issue imply that I do not need to work on this issue any more @JeffBezanson ?

[tkelman]

If you would like to squash this, and someone is willing to take a stab at revising it for grammar, try the following steps.

# Make a new clone from your fork
git clone https://github.com/Sisyphuss/julia julia-Sisyphuss
cd julia-Sisyphuss
git remote add Sisyphuss https://github.com/Sisyphuss/julia
git remote add JuliaLang https://github.com/JuliaLang/julia
git fetch JuliaLang
git rebase -i JuliaLang/master
# change all commits except the first one to squash
# review `git log`, and `git diff HEAD~ HEAD` carefully
# to ensure you only have one commit with the latest content
# if you like the content, do
git push Sisyphuss +master

Whoever's willing to revise the grammar could probably do this themselves without too much trouble though.

[JeffBezanson]

Mostly the problem is that the text is too long, and uses unnecessarily loaded and adversarial language, e.g. mentioning "competitors" and "claimed" properties. None of that is relevant. All we need to do here is simply explain what to write and what not to write. This text has numerous problems beyond grammar; the grammar is not so bad.

[tkelman]

This part of the documentation could really use more elaboration. From the mailing list, stack overflow, and naively written Julia code out in the wild, many performance behaviors remain highly unintuitive and difficult for new users to grasp. That's going to remain the case as long as the documentation stays overly concise.

[Sisyphuss]

The major problem of the current performance tips is: it looks more like a memo for skillful developers than a help document for new beginners. For the sake of pedagogy, more elaborated paragraphs are needed. Besides, when I rewrote this document, I was always thinking about my target readers--who are likely to read this chapter. Those who care about performance are most likely to turn to Julia simply for its high speed (instead of other innovations), so naturally they will be critical and compare Julia with other languages (at the speed aspect). Therefore, my language is not "loaded and adversarial" as @JeffBezanson mentioned, but just tailored to the potential readers.

[ScottPJones]

I agree with @JeffBezanson that the first paragraph should be reworked a bit, I was exactly one of those newcomers to Julia two months ago, compared it to C and Python, got bad results, but persisted even so, because of the promise I saw in Julia (or because I'm incredibly stubborn, take your pick!).
Instead of

Some users reported that their Julia programs did not run as fast as expected, maybe even slower than their Python counterparts, contrast to the high performance claimed of Julia project. However, this inefficiency is largely due to the failure of conformity with the Julia programming norm. To help users better benefit from the high performance of Julia, this page presents some tips, by following which, users may see a significant speed-up (around 100x ~ 1000x) in their programs.

maybe something like:

In order to achieve the high performance which is possible in Julia, achieving the speed of C and Fortran code, with much less code, it is often necessary to change the way things are coded compared to other languages, to take advantage of the type inference analysis and multiple dispatch features of Julia.
This page presents a number of tips, which when followed, can often help users achieve many orders of magnitude improvement in the speed of their programs.

I think that would seem less confrontational, while still getting the message across...

[quinnj]

Stale Doc PR; seems like there's some consensus around cleaning up the performance tips a bit, but with the goal of still keeping the language simple and to the point.