Rust explained using easy English

by Santosh83 • 6 years ago

335 79 6 years ago

zer• 6 years ago

I 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• 6 years ago

I assume the markdown is the source and that other presentational forms will follow.

nicolodavis• 6 years ago

Do 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__2• 6 years ago

I'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• 6 years 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.

bscphil• 6 years ago

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).

I think you're getting at an important issue here. I've been programming (as a hobbyist, not a professional) for over a decade, have contributed to a bunch of open source projects, written software of my own. Mostly in languages like Python, but I've dabbled with C, Rust, etc. The stuff about lifetimes in this guide is still borderline incomprehensible to me. The reason for that is that the basic issue here isn't the difficulty of the language used to describe the concept, but that the concept itself is complicated. Maybe it needs to be complicated, but I don't think there's any way to distract from the fact that Rust is a very hard language to learn.

a-ve• 6 years ago

https://fasterthanli.me/blog/2020/a-half-hour-to-learn-rust/

This is also a good introduction.

Phillips126• 6 years ago

This is great, thanks for sharing.

pantulis• 6 years ago

I 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• 6 years ago

This could really use a Table of contents

elbear• 6 years ago

It has one now

0xDEEPFAC• 6 years ago

As 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/

franga2000• 6 years ago

I'm confused. Only u8 can be cast to char, but char is 4 bytes long? How do those two things works together?

lifthrasiir• 6 years ago

Because 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

ChrisSD4• 6 years ago

Additionally 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).

throwaway7446782• 6 years ago

I 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• 6 years ago

A 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#meth...

pelliphant2• 6 years ago

somewhat of a rust noob: but as I recall there is a difference between string and array of chars.

string use utf-8, which is 1 byte for the most common characters.

char is unicode

prerok6• 6 years ago

I 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.

throwaway7446782• 6 years ago

Unfortunately, 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".

prerok6• 6 years ago

I 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.

Tobu2• 6 years ago

Inference works in all Romance languages, as well — it's a Latin word and this use is extremely close to its use in logic (going back to Aristotle).

Anyway, I'd consider simple english a tool for introducing new concepts.

Learning programming still means that the concepts must be introduced, and having a new word to bind the new concept seems good to me.

prerok6• 6 years ago

But not in Slavic languages :)

I guess my point was just that I find the write up in "simple English" the same as the Rust book (I have just been going through it).

I would not have any objections if the term is introduced later on. To rely on it from the start just seems... well, the same as the book :)

skocznymroczny• 6 years ago

As a non-native speaker, I'd find "type deduction" much easier to grasp than "type inference".

prerok6• 6 years ago

Agreed. Asked around here a few people and "deduce" is more wide spread than "infer". A lot of people don't know the meaning of either, though, and it doesn't help that deduction's first translation is related to the mathematical operation :(

I would still suggest to go with automatic :)

Animats• 6 years ago

Very 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/087795...

marliechiller• 6 years ago

thank you for this, that is a fascinating snippet of information that sent me down a rabbit hole

arethuza• 6 years ago

Similarly, 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• 6 years ago

That was a pretty cool TIL, and really explains his obsession with language in 1984!

kranner• 6 years ago

Thanks for mentioning the book, it seems really interesting!

The book can be borrowed at https://archive.org/details/orwelllostwritin00orwe

jimbob45• 6 years ago

I 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• 6 years ago

only `u8` can be cast as `char`, not `i32`

Can someone explain that in basic english?

turndown• 6 years ago

Say 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.

ChrisSD4• 6 years ago

It can fail. Use `try_into` instead.

walty8• 6 years ago

I 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• 6 years ago

found this on reddit for this post:

"I applaud this. And it reminds me of the up-goer five. https://xkcd.com/1133/"

dgellow• 6 years ago

You link doesn't work because of the double quote at the end.

Working link: https://xkcd.com/1133/

quercusa• 6 years ago

Randall Munroe did a whole book in this style: https://xkcd.com/thing-explainer/

It's a lot of fun.

aazaa• 6 years ago

You can try your hand at writing in this style here:

https://splasho.com/upgoer5/

shahinrostami2• 6 years ago

Interesting 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• 6 years ago

Because 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....

[1] 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. :)

Fiahil• 6 years ago

As a non-native English speaker, I can read this faster than my usual technical content! Great work!

hellofunk2• 6 years ago

The 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• 6 years ago

For 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• 6 years ago

Sometimes 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• 6 years ago

Each variable is of one type. If you change the type, you must declare a new variable.

redleggedfrog• 6 years ago

Such simple language allows my mind to instantly start composing syntax. Excellent work.

giancarlostoro6• 6 years ago

I'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• 6 years ago

The 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.

giancarlostoro6• 6 years ago

Most 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• 6 years 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. I am (slowly) collecting examples and trying to improve the ecosystem.

pornel2• 6 years ago

File 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.

giancarlostoro6• 6 years ago

That's interesting I didn't even think about that, then I'm not sure why it doesn't work. One case I still remember was where Actix (web framework) had docs pointing to severely older versions of the software, while the readme pointed to another, and none of them matched up quite right at the time... It was just not useful. If the examples work but you don't know where to go from there what can you even do at that point...

joshmarlow2• 6 years ago

third party libraries (even extremely popular ones) have outdated example code or docs that are inconsistent with actually released versions.

That's actually one of my big pet-peeves about OSS. This is especially annoying because the Rust ecosystem already has a really nice solution to the problem - skeptic ([0]).

Skeptic finds Rust snippets in markdown files and dynamically builds tests to run them. So if your docs go out of sync with your code, `cargo test` fails.

[0] https://github.com/brson/rust-skeptic

giancarlostoro6• 6 years ago

Kinda sad it looks like that was last updated 2 years ago

s_c_r• 6 years ago

This happened to me the other day with sqlx. Tried to duplicate the quick start example and got a slew of errors. I should make a ticket, maybe I did something wrong.

hellofunk2• 6 years ago

The 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• 6 years ago

Note 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• 6 years ago

Nice!

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• 6 years ago

this is great. it really helped demystify rust and get me started writing some. thank you.

karmakaze• 6 years ago

Word 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?

Rust explained using easy English

Related Stories