11 ms·
Rust explained using easy English
- zer 6y agoI like the general idea. I haven’t got the time to do more than skimming right now but I already feel that a single markdown file (especially without a table of contents) isn’t the right medium for this.
- berkes 6y agoI assume the markdown is the source and that other presentational forms will follow.
- nicolodavis 6y agoDo you have specific examples of what is difficult to understand in the standard books for a non-native speaker? Just asking out of curiosity and maybe readers can learn a thing or two about making documentation more accessible.
- mhh__ 6y agoI'm not overly familiar with rust's documentation in particular but in my limited experience of teaching programming to a few unfortunate souls, the issue is usually figuring out what framing device to use. The actual level of English in good documentation is usually fairly "low" - i.e. keep it simple, assume your reader wants to learn (Too many people suffer from I'll let you google that for me). That and a lot of non-native speakers probably speak better English than me (I know more words but I'm lazy) I know how to program, I've been bitten by memory bugs - rust's design makes sense to me (i.e. the borrow checker is relatively intuitive because I've written and worked on compiler/s). That is difficult to convey in 10 minutes to someone who only knows how to plot a graph in python (for example). My approach is usually to state all my assumptions as I go, while naming as much as I can as I go (e.g. googling for operators can be very difficult) when explaining things. In writing, I find that writing documentation away from the code can be quite fruitful otherwise the overall structure and meter of the code can be hard to divine.
- da39a3ee 6y ago> someone who only knows how to plot a graph in python (for example). Hey, I've been writing Python daily for 12 years and I struggle with that! First you have to get matplotlib installed. That often works nowadays, but you have to be sure you've installed numpy first, and on a bad day you'll find yourself looking at some sort of C compiler error and copying stuff from stackoverflow to make libgfortran be found or whatever. Then you try to remember the bizarre way people import matplotlib. Your mind briefly flits to memories of blog posts explaining that matplotlib has two parallel APIs, and you start feeling annoyed about that. Then you start feeling annoyed that one of the APIs is based on matlab; why should a key part of the python ecosystem be apeing matlab? It's not like anyone has ever thought matlab had APIs, or anything really, worth emulating. Anyway, it's something like `from matplotlib.pyplot import plt`, or some nonsense like that. So you spend a few minutes failing to remember, and then googling for it with a rising sense of frustration. Then you get this error: _RuntimeError: Python is not installed as a framework. The Mac OS X backend will not be able to function correctly if Python is not installed as a framework. See the Python documentation for more information on installing Python as a framework on Mac OS X. Please either reinstall Python as a framework, or try one of the other backends._ And now you're really quite annoyed. What the fuck is a framework? It's some MacOS thing but it's always been clear that it's a non-UNIXy concept that you don't want to and shouldn't need to know and you kind of suspect it shouldn't even exist. But holding that opinion would require finding out what it is. So you google for how to overcome that. And then... there's some weird thing where you have to put a line in the middle of your inport statements before importing matplotlib... and finally you wish you hadn't been so stubborn and had just used an IPython notebook, but you just kind of hate them despite how beautiful and well-engineered they are. They can't be version-controlled, you hate typing code into your browser, you always end up with an incomprehensible mess of mutable state, etc. I used to use R and, back then, I enjoyed making plots and did so efficiently and reasonably well.
- mhh__ 6y agoIgnorance is bliss when you can just copy and paste example code and swap out the plotted function (is what I was alluding to)
- 6y ago
- a-ve 6y agohttps://fasterthanli.me/blog/2020/a-half-hour-to-learn-rust/ https://fasterthanli.me/blog/2020/a-half-hour-to-learn-rust/ This is also a good introduction.
- Phillips126 6y agoThis is great, thanks for sharing.
- pantulis 6y agoI feel this is like the condensed version of a book. Very useful, gets the job done so you can make yourself a quick picture of what is it like programming in Rust. This not IMO newbie programmer material so I think a caveat could be added.
- rapsey 6y agoThis could really use a Table of contents
- elbear 6y agoIt has one now
- 0xDEEPFAC 6y agoAs the author of a programming language ; ) I find this article very inspiring. I just want those new to programming to understand the joy of systems and simple graphics programming like in the ol' Turbo Pascal days! http://www.adapplang.com/ http://www.adapplang.com/
- franga2000 6y agoI'm confused. Only u8 can be cast to char, but char is 4 bytes long? How do those two things works together?
- lifthrasiir 6y agoBecause char's range has a hole from 0xd800 to 0xd8ff (surrogate pairs [1]) so not all u16 values (or larger) can be safely converted to char. [1] https://en.wikipedia.org/wiki/UTF-16#U+D800_to_U+DFFF https://en.wikipedia.org/wiki/UTF-16#U+D800_to_U+DFFF
- ChrisSD 6y agoAdditionally Unicode only goes up to U+10FFFF (1,114,112 code points) which is far short of a full 32 bits (4,294,967,295 values).
- deleted 6y ago[deleted]
- deleted 6y ago[deleted]
- throwaway744678 6y agoI found the paragraph about char a bit unclear; especially when explaining that all chars are 4 bytes long, and std::mem::size_of_val("Hello!") is 6 bytes. I would have expected it to be 24 bytes long!
- sjustinas 6y agoA Rust String is encoded as UTF-8, it is not an array of char-s. You can get an iterator over individual codepoints using the chars() method. https://doc.rust-lang.org/std/string/struct.String.html#method.chars https://doc.rust-lang.org/std/string/struct.String.html#meth...
- jiggunjer 6y ago
- prerok 6y agoI like efforts like this that try to use different wording to explain the same concepts. That said, this document still uses words I would not consider to be "simple English". There are many such cases in the document, but let's take for example "inference". There is a definition of what "type inference" is in the first paragraph of the section. But the reader must still then learn this phrase at the same time as learning the programming language. Maybe a simpler English statement would be "Automatic types", using the word automatic, which is more wide spread and is adopted in many languages. The meaning is not as precise but the document can then further explain what it is. I am not a native English speaker but have become so used to using it that it is sometimes difficult to know which terms cause issues to programming language learners. Perhaps HN is the wrong place to ask this but I would be very interested in knowing which terms other non-native speakers have problems with.
- throwaway744678 6y agoUnfortunately, we still need technical terms to define precise concepts. I'd argue that "inference" in "type inference" is not something a non-technical native English speaker would understand either, so it's less a matter of "simple English" vs. "technical vocabulary".
- prerok 6y agoI agree. The problem is that most people learn these precise technical terms first in their own language and must then learn them also in English (well, in truth, for me it was the other way around :) ). I think that this write-up could use a simpler English, as it is titled, then the reader can later proceed to learning the more precise technical terms in other material.
- chousuke 6y agoPersonally I don't know what half of my technical vocabulary translates to in my native language :P I know what type inference means and I'm pretty sure I could explain it in Finnish but I have no clue what the "standard" jargon is if it even exists. I have lots of vocabulary that is "English-only"; it's especially noticeable if I'm asked to translate something, as coming up with a translation can take a while even though I can effortlessly understand the source sentence.
- Animats 6y agoVery nice work. It's a good exercise to put complicated ideas into very simple language. George Orwell had that job during World War II. The BBC used to broadcast news to the British Empire in India and Hong Kong, using Basic English. Orwell's job was to translate the news into Basic English. He later wrote that this is a political act. Converting news to Basic English means taking all the ambiguity out. If a political statement was ambiguous, removing the ambiguity means making a political decision. Someone has to decide what the statement really means. That's where Newspeak, in "1984", came from.[1] [1] "Orwell, The Lost Writings", https://www.amazon.com/Orwell-Lost-Writings-George/dp/0877957452 https://www.amazon.com/Orwell-Lost-Writings-George/dp/087795...
- marliechiller 6y agothank you for this, that is a fascinating snippet of information that sent me down a rabbit hole
- arethuza 6y agoSimilarly, Room 101 was a room where he had to suffer long boring meetings. Many years back I used to suffer long meetings in another 101 meeting room - I suspect that numbering scheme might be quite common. [Edit: Mind you in the same building a lecture room where I used to suffer maths lectures is now a bar! The building having been converted to a hotel.]
- alfiedotwtf 6y agoThat was a pretty cool TIL, and really explains his obsession with language in 1984!
- kranner 6y agoThanks for mentioning the book, it seems really interesting! The book can be borrowed at https://archive.org/details/orwelllostwritin00orwe https://archive.org/details/orwelllostwritin00orwe
- jimbob45 6y agoI think a wiki format might better suit this presentation. It’s tough because you wash to be comprehensive but when you have one page, that means you’ll have to clutter your document with all the comprehensive details. In a wiki, you can hide those details in deeper pages for only the more curious reader to find (or for those on their second read-through). Nevertheless, this document is phenomenal and I will refer to it in the future.
- Donckele 6y agoonly `u8` can be cast as `char`, not `i32` Can someone explain that in basic english?
- turndown 6y agoSay you have eight books of equal size on a shelf. It's easy to put these eight books on another shelf of equal size or larger. If you have a shelf holding thirytwo books, it is impossible to fit them all on the smaller shelf, so it's better to simply not do it.
- deleted 6y ago[deleted]
- ChrisSD 6y agoIt can fail. Use `try_into` instead.
- walty8 6y agoI think the paragraphs are simple enough, but my personal preferences is, some paragraphs better come first than others. I am not sure if it's the same to others, but for me to learn a language for the first 15 minutes, I am really not interested with the differences of signed vs unsigned integers. I may have look of this when I got stuck somewhere later. I think a better order will be: 1. play ground 2. hello world 3. control flow 4. function declaration 5. string, list and dict 6. featured stuff with this language (e.g. threading, async call) I should be able to write basic stuff and play around with the above. Then I would try to sort out all kinds of remaining pitfalls myself :)
- leorio 6y agofound this on reddit for this post: "I applaud this. And it reminds me of the up-goer five. https://xkcd.com/1133/" https://xkcd.com/1133/"
- aazaa 6y agoYou can try your hand at writing in this style here: https://splasho.com/upgoer5/ https://splasho.com/upgoer5/
- shahinrostami 6y agoInteresting tool - I tried pasting in your comment and it seems like the word "style" is not permitted! Uh oh! You have used a non-permitted word (style)`
- programbreeding 6y agoBecause it isn't in the list of accepted words[0] (most used words) as inspired by XKCD[1]. [0] https://splasho.com/upgoer5/phpspellcheck/dictionaries/1000.dicin https://splasho.com/upgoer5/phpspellcheck/dictionaries/1000.... [1] https://xkcd.com/1133/ https://xkcd.com/1133/ Edit: I just figured out you might fully realize that and were probably just pointing it out to OP. Ignore me. :)
- shahinrostami 6y agoIndeed I did :) but still useful to have the links for other interested readers!
- Fiahil 6y agoAs a non-native English speaker, I can read this faster than my usual technical content! Great work!
- hellofunk 6y agoThe discussion about shadowing variables doesn’t seem to make a very good case to me about this feature. Why would you want to introduce all those variables on the stack, each of a different type (even if they have the same name, presumably they are new pieces of stack memory)? Why not just mutate an existing variable each time?
- asplake 6y agoFor me, understanding shadowing adds to one's understanding of what 'let' means. Whether the shadowed variables each get new memory I'd be happy to leave to the compiler/optimiser.
- miccah 6y agoSometimes you need a different type and you don't care about the intermediate values. Parsing a string into an integer is a good example. Once you have the integer, generally you don't care to use the string anymore. let num = String::from("10"); let num: i32 = num.parse().unwrap();
- chrismorgan 6y agoEach variable is of one type. If you change the type, you must declare a new variable.
- redleggedfrog 6y agoSuch simple language allows my mind to instantly start composing syntax. Excellent work.
- giancarlostoro 6y agoI'm picking up Rust again, and one of our lead architects tried to pick it up but ran into the same issues I've ran all along: third party libraries (even extremely popular ones) have outdated example code or docs that are inconsistent with actually released versions. So in the meantime I will focus on learning the out of the box features of Rust. It is a shame because I love the potential of Rust but it seems that not much has changed in the two years since I last touched it in the regards to documentation for external projects. I still am not good enough with Rust to start producing my own projects as a result, which in other languages you can do rather quickly. I hope the ecosystem matures in this regard because I love everything else, the tooling, the build system is very modern and mature as best as I can tell.
- spoiler 6y agoThe issues with documentation aren't really something I'd attribute to the Rust ecosystem, but just to people/humans in general. I've had this problem with every language I worked with: JS/TS, Haskell, C/C++, Go. Eg,the C++ boost docs are IMO completely decrepit, but people still manage to be productive using it. If you see a mistake in the docs, open an issue (or a PR), it only costs you little time.
- giancarlostoro 6y agoMost of my contributions on GitHub are tickets, so I just might have to. Thing is I have a rule of thumb that if I can't get a language to work in about 15 minutes, I ditch it. But now that I do want to get into Rust I may just have to write up tickets when I run into issues.
- tome 6y ago> I've had this problem with every language I worked with: ... Haskell ... By the way, if you see outdated Haskell docs please report them on https://github.com/tomjaguarpaw/tilapia https://github.com/tomjaguarpaw/tilapia. I am (slowly) collecting examples and trying to improve the ecosystem.
- pornel 6y agoFile bugs for these! I wouldn't be surprised if readmes were rotten, but you should be able to rely on examples in docs and example programs in Cargo projects, because they are automatically built and run during unit tests.
- hellofunk 6y agoThe most interesting thing I’ve learned yet from this, and I’m not quite done with it, is that you can pass a constant (let) to a function, which can accept it as mutable, and therefore actually mutate data that the caller thinks cannot be mutated! I’m not sure how I feel about this.
- kimundi 6y agoNote that that is passing by value, so its moving/copying ownership. Its like having a immutable integer variable and copying it to a different mutable variable.
- dyingkneepad 6y agoNice! Sometimes I wish we had a basic "algorithms" language that was used absolutely everywhere, and every book everywhere teaching another language would assume the person knows how to program using the basic language and then teach the new language as a diff of the basic one. Why do I say this? Because as someone who is versed in quite a few languages, I find the signal to ratio of these texts to be uncomfortable. For example, I know C really well, so the explanations of integer sizes are irrelevant, I know what is shadowing, etc., but the explanation of the return statements is really useful, the variable declaration is interesting, so I keep having paragraphs I can skip followed by paragraphs I have to read, followed by paragraphs I can skip, etc. I get tired quickly when reading like this.
- stOneskull 6y agothis is great. it really helped demystify rust and get me started writing some. thank you.
- quda 6y agoExcellent guide. Congrats!
- karmakaze 6y agoWord choices are very important. Yes we want to use smaller common words but not to the point of being misleading. > Type inference means that if you don't tell the compiler the type, but it can decide by itself, it will decide. The word 'decide' implies that there was a choice that was made. I would think of inference more as 'determine' as the process is deterministic just not always successful. Or are there actual cases where the compiler infers a type that's close but not entirely correct?