I will say every programming language I’ve used, I’ve had to worry about overflow. That’s just been a fact of life for me. My guess it’s a speed thing. If the compiler doesn’t need to worry about overflow it can perform the calculations faster. If it handles overflow then all calculations get slower. So it’s a trade off between safety and speed. Julia choose speed over safety, and quite frankly if it used computational safety over speed, I would probably be using another language. 
1 Like
I’m not sure that your specific recommendation is as clear to us as it seems to be inside your own head. Where, exactly, should it be put, and what should the phrasing be? In looking at it, here is my thought process:
- should it go on the first “chapter” of the manual? That’s really about how you launch Julia, how to quit Julia, and the various command-line options. That doesn’t seem right.
- should it go in the next chapter on variables? Well, that’s about allowed variable names and naming conventions. Doesn’t seem right.
- how about the next chapter on numbers? That seems perfect! But wait, it already is there: just about the very first thing you see is a table of min/max values for each type of number. And then just below that there’s an entire section, with a big juicy header, called “Overflow behavior”.
My conclusion: this box already has a checkmark next to it. To me it seems we’ve already bent over backwards to make this clear and put it in the very first possible place you could deposit this information. If you disagree, please make a concrete suggestion for exactly where to put it and with what phrasing.
I think you’ll find a lot less resistance when your suggestion is made more concrete and constructive.
37 Likes
Why don’t you make a pull request to the documentation with the improvements you would like to see, rather than berating people for not agreeing with you? It should be doable through the web interface, and quite simple.
2 Likes
Honestly, I think it’s a pretty high bar to set for newcomers, “you can’t voice comments or critique unless you have enough overview of the code / docs to do a PR”. I think that’s completely fair to ask of an experienced developer voicing a critique (“let’s see what you mean in concrete terms”) but used like this it risks becoming a way to quell criticism from anyone not part of the core community.
Yes, it wasn’t nice of @gevis to call the community self-complacent and say julia would not end up being a product of quality, but it did come as a response to some also quite provocative remarks from @Tamas_Papp . So if we can put the heated emotions down for a moment and focus on the core topic of the discussion?
Even though @gevis’ idea of putting something on integer overflow in “the beginning of the documentation” is not practical with how it’s currently structured, there’s an important point in that, which is that things like integer overflow are part of the knowledge you need to have to use Julia safely. Just like you need some understanding of e.g. memory allocation. This is similar to C, Java, numpy etc, but different from base Python, R and Matlab, languages that today take up an enormous proportion of what would be julia’s potential user base if the language grows. What’s reflected here is, I think, exactly julia’s attempt to straddle across both high and low-level languages, with it’s ambition to resolve the two-language problem. I teach an R course to biology MSc students, and I’m pretty sure they would blank out completely if asked about integer overflow (as would frankly my colleagues). They simply don’t have enough of a concept of how computers work to process it. But I personally am not resigned to the fact that julia should not appeal to my students and colleagues.
The core point here being that to teach julia we do need to emphasize concepts that are more computer fundamental and close to the metal than when teaching eg R and Python, and so we should consider this if adapting teaching materials developed for these high-level languages. But changing that culture slightly should, in my opinion, by no means entail that julia will continue being niche. Students should be willing to learn, as these concepts can be seen to have immediate usefulness.
About the manual, I love it. Read it back around julia-0.4. I’m pretty sure I read about integer overflow, then promply forgot it
37 Likes
I’d add that as someone who knows a lot about computers, including a minor in computer science, and experience teaching people programming, and who has used among others languages like Common Lisp, Scheme, Erlang, bash shell, R, matlab, Perl, C, C++, Stan, SQL, python, Awk, m4, prolog, etc. There is a lot of stuff one needs to know to be a good programmer. Most people never get there. In fact, many people who consider themselves good programmers aren’t even close to there, their conception of what is possible just doesn’t include lots of stuff.
Julia should be at least usable by these people who sit on top of the small pile and think of themselves as good programmers because they have written many functions in R or Python or something and understand say dictionaries vs arrays.
But Julia is capable of scaling all the way up to people who want to write a compiler that compiles a domain specific language for solving finite element problems, does proofs on the resulting problem to show that certain error bounds are not exceeded when combining parallel calculations, and then automatically parallelizes the problem to a HPC cluster, combining the results back together and then animating the resulting solve into a video.
That kind of wide applicability inevitably will require a wide variety of documentation. There should be things about “getting started with programming… here is a REPL… look it can be like a scientific calculator” to “if you have some experience with Matlab here is how to solve some basic ODE problems and do some graphs, and here are some gotchas and things you should know about how Julia is different” all the way up to “here is a 4th year computer science textbook for numerical algorithms written with Julia in mind” and “here is a 2 semester course in compiler writing designed for people wanting to create domain specific languages using julia”
You just can’t get it all in one document.
EDIT: also add that I’m still just a new julia user. I need to force myself to use it more in order to build up my comfort level. It’d be great if there were kind of a document that was a quick-launch into Julian style for doing numerical/scientific programming someone who doesn’t need the whole hand holding through the beginning bits, install, pkg manager, REPL, etc but wants to see what idiomatic code looks like for solving nontrivial science type problems.
5 Likes
We very recently had a megathread on improving documentation; one of my main takeaways was the pointer to the fact that there isn’t a single thing called documentation; not only are the potential target audiences different, but there are four different kinds of formats needed for solid documentation:
The Julia manual is largely a reference, with some parts mixed up with explanation. There is definitely room for improvement in our documentation and onboarding references.
Suffice it to say that this is very well-trod ground in this discussion forum!
6 Likes
Making suggestions and discussing things is definitely fine for anyone, but when someone uses the tone of this OP, I think it’s appropriate to point them towards the opportunities for simply contributing the changes they want to see.
2 Likes
The problem is, which good example? Tamas’ point that everything in the FAQ is actually frequently asked suggests that, if we take this approach, we’d have to basically put the entire FAQ at the beginning.
There’s an argument to be made for that, but I’d personally be against it. The main language docs serve a number of purposes - they are both a technical reference as well as a narrative introduction to the language. I think that later purpose would be disrupted if a bunch of tricky gotchas were put at the beginning before a new user had context for them.
Note: no one replied by just telling you to read the documentation. Many people provided thoughtful replies, explanations, examples of counter arguments. The second reply (after a silly joke, which was explicitly noted as such) was a really clear statement that
I for one have never had to worry about integer overflow. It just doesn’t come up in my domain.
Many of the posts after that were other solutions and work arounds, links to helpful packages etc. Many people don’t agree with you. That’s not the same thing as toxicity.
Your response to all of this was, “yeah, but python does it differently, and is better.” And “if you don’t do what I say, Julia will just be a niche language. Not quality.” To understand why this was met with a bit of negativity, you must understand that people are constantly coming into this forum saying, “if you don’t do <thing that just occurred to me>, Julia won’t grow.” As if there aren’t hundreds of people putting hours and hours of their time into thinking about how to make the language better.
For the record, that’s not actually what happened. You suggested something you thought would be an
Improvement, and people disagreed with you and explained why. Pretty cordially, I think. You responded with hostility. Yes, @Tamas_Papp’s respose was perhaps a bit intemperate, but it’s pretty tedious to constantly have some variant of the conversation
“I have a thought, you should do X”
“Well, X might not be the best idea. Have you considered Y or Z? Here are some links to places that this has been discussed at length.”
“X is better for me. Do X or Julia is bad and won’t grow.”
“Sorry you feel that way. Here are some ways to do X if you want. We’re unlikely to do that as a default for reasons A-E.”
“Well, I prefer X, and so does some guy I know. I can’t believe you wouldn’t just do X when it’s obviously better.”
“Well, perhaps julia isn’t the right fit for you”
“Wow, julia community is so toxic!”
11 Likes
I believe you are referring to this?
2 Likes
I don’t think there is such a bar, either explicitly or implicitly.
Those who ask about the reasoning that led to a particular design choice of Julia usually get a lot of detailed answers here.
But to echo @tim.holy above: integer overflow is already discussed in the docs pretty early. Reasonable people can disagree about whether it can be done better, but it is not obvious how. A PR is the right way to move forward here.
Incidentally, making a PR is nice way to signal that someone wants to be a stakeholder in the Julia community. While anyone can criticize, it is important that changes to the language (including the docs) serve the actual users of Julia.
3 Likes
My suggestion would be: In the getting started section, as the second paragraph (i.e. after “first, download Julia”) insert a paragraph that reads something like:
If you are coming to Julia from one of the following languages, then you should start by reading the section on noteworthy differences from Matlab, R, Python, C/C++ or Common Lisp. This will help you avoid some common pitfalls since Julia differs from those languages in many subtle ways.
Edit: Since this post received several “likes”, I turned it into a pull request.
26 Likes
That’s a good idea, though it wasn’t trivial for me to spot integer overflow (e.g. it’s not mentioned under R). I feel like that section could be improved with some subheadings etc. (yes I know what someone’s going to say now 
).
3 Likes
Integer overflow and integer sizes are really basic concepts in every programming language. Coming from C++, the mistake in your code seems way too obvious to me. But in Python it’s different, so that may be causing the confusion.
All the ideas about improving the docs here are good, but I just want to clarify one thing that was often repeated.
The criticism for Julia here is completely undeserved. Yes, it can be used as a scientific calculator, and not just any scientific calculator, but also a very good one. I have previously used Python and Lisp REPL extensively and neither comes even close.
You can try solving some problems from https://projecteuler.net/. Many of the beginner ones take just 1 or 2 lines in Julia.
Edit: This library may be a nice addition to Julia’s use as scientific calculator.
7 Likes
I agree. I now use the Julia repl instead of Python repl for quick calculations, and ironically (considering this thread) one of the benefits of Julia is its support for signed and unsigned integers of various sizes. I work with embedded systems so close-to-hardware behavior of those is really handy!
Actually it is a very good point. Thank you for the reference.
As it is explained in the video, tutorial should be learning oriented and quite different from what is called there as a "reference,” which I would call just a documentation.
By reading a tutorial, the reader should learn some small portions of the material step by step. So, the material should be grouped in such a way that all facts related to some topic be in one place. And, for a tutorial, it would not be bad if some of these facts will be repeated in several places. However, it is bad for a tutoral if the reader could get all the facts related to one topic only after reading it from the beginnig to the end.
In our case, as it has already been pointed out, the information about dealing with integer overflow are scattered over the Julia “tutoral”: namely, in the Integer Overflow subsection of it, mentioned is the possibility to use BigInt type while the information about the SafeInteger.jl has been mentioned only at the very end of it, namely, in the FAQ section. May be, also a bit earlier as well, but it actually does not matter because inbetween there are so much information that it makes it completely impossible for the learner to connect the related facts together. Especially while in between there is a section on metaprogramming that can kill almost anyone who does not know Lisp and can read the source code of Julia parcer.
That was one of the main points of my original post, in which I also mentioned that I am aware of the fact that integer overflow has been mentioned in the tutorial, however, in my view, it is not enough.
Nevertheless, in reply, I was shoven in my throat the same fact that integer overflow has been mentioned in the tutorial, and moreover, somethere at the end of it, has been mentioned the SafeInteger.jl package.
Yes, it was. However, this was not enough. Especially at the time when Python has already established the standard for dealing with integer overflow by a higher level languages.
Once more: you are free to make any design choices on dealing with integers, and the current one, with the SafeInteger.jl package is quite ok. However, if you state in your manifest that creating Julia you wanted to create “something as usable for general programming as Python” and in many other places make users of Python expect that Julia is like Python but better, you should take the trouble to warn them about the most dangerous pitfall that wait for them in the most basic part of Julia programming language in such a way that they simply cannot fail to understand or miss its importance.
Mixing it with all other small differences that Julia and Python have is not a good substitute for this warning and explanation as well, at least in the tutorial.
Once more: for documentation, or reference guide, it may be ok to have this description only once, but not for the tutorial.
And, yes, taking into account the reference sited by Tom Kwong, the current Julia “tutorial” should be splitted to the tutorial and actually documentation or reference guide as it is called in the video.
P.S. I will also reply to other relevant comments later.
I think everyone has said their fill and I really don’t see this continuing in a productive direction.
Can we all table this now?
4 Likes
I object against it as I have not replied to all yet.
Moreover, it is high time to return to the productive direction.
I am confused, the document you are referring to and has been discussed above (to the best of my understanding) is in fact the Julia manual/documentation and not a tutorial. So it seems maybe the issue here is a misalignment of expectations about the nature of the document in discussion?
I think no one will object if you write a nice tutorial explaining integer overflow to physics students and publish it. There is always room for more quality Julia tutorials.
2 Likes
Did you take the trouble to view the video in the reference above explaining how documentation should be organized and what is the difference between tutorial and reference guide?
Currently the Julia tutorial is the mixture of them.
So far I have been told that I am not even able to read and understand very basic notions.
I do not think that anybody would be interested in what such a person can write.
Moreover, yet from the very beginning I was told that the documentation is alredy in the best possible state and should not be changed.
The discussion whether there should be a tutorial section included in the official documentation is a different discussion than the original post to the best of my understanding. Anyway, sorry if I misinterpreted your last post.
I don’t think that this is true at all. I’m sure that if you write a nice tutorial emphasizing the things you find important, people will appreciate it.