Rust explained using easy English
github.com
github.com
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...
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.]
The book can be borrowed at https://archive.org/details/orwelllostwritin00orwe
This is also a good introduction.
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 :)
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.
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.
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.
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.
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.
Tested it on clap (no specific reason, just have a checkout locally) and it ran 314 snippets from the docs so seems to work.
let num = String::from("10");
let num: i32 = num.parse().unwrap();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.
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.
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.
I think this is only possible true for people who speak languages with large programming communities - Chinese and maybe Russian - but I doubt it’s true for anyone else.
Unfortunately, we in the industry largely don't follow these updates so in our conversations we use English terms. People just graduating, however, may be exposed to the English terms anew when they start working.
A dilligent student would have studied material in English as well but it is possible for people to get to a Masters in Computer Science and do all their studying in our native language.
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.
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 :)
I would still suggest to go with automatic :)
This not IMO newbie programmer material so I think a caveat could be added.
Just asking out of curiosity and maybe readers can learn a thing or two about making documentation more accessible.
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.
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.
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.
Uh oh! You have used a non-permitted word (style)`[0] https://splasho.com/upgoer5/phpspellcheck/dictionaries/1000....
Edit: I just figured out you might fully realize that and were probably just pointing it out to OP. Ignore me. :)
https://doc.rust-lang.org/std/string/struct.String.html#meth...
Languages that were developed before the advent of Unicode, like C and C++, frequently leave the encoding of strings up to the system; but this can be complicated, because there are a number of different legacy 8 bit encodings, along with legacy encodings that don't fit into 8 bits. So they have two character types, char and wchar_t; char is a type that can always encode at least 8 bits, and wchar_t is an implementation defined wide character type, which is 16 bits on some platforms and 32 bits on others.
When Unicode was first designed, and released as Unicode 1.0, it was envisioned as a 16-bit universal encoding, with the expectation that you would use it just like 8 bit character encodings but with 16 bit character types instead. This encoding is known as UCS-2.
However, experience and unification of the Unicode standard with ISO 10646 showed that 16 bits would not be sufficient for all of the characters in all of the world's writing systems; in order to fit CJK characters into that 16 bit encoding, a large effort was made to unify characters from different languages that represented basically the same thing but might be written slightly differently in Traditional Chinese, Simplified Chinese, Korean, Japanese or the historical Vietnamese writing system. Additionally, a lot of decisions had to be made about inclusion of historical or obscure characters, and so there were many characters which couldn't be encoded properly in early Unicode.
This led to Unicode 2.0 introducing a surrogate character mechanism, now known as UTF-16, in which certain unused ranges of code points were used in pairs to represent a wider range of code points, in order to expand Unicode from a single 16 bit plane of characters to 17 16-bit planes.
Meanwhile, Ken Thompson and Rob Pike adapted an earlier 8-bit encoding of ISO-10646 called UTF-1 into UTF-8, which had a number of desirable properties; it was a superset of ASCII, the interpretation of the ASCII subset of bytes never depended on state, and it was self-synchronizing, so if you started reading in the middle of a multi-byte character, you could always find the start of the next character.
This meant it was possible to use UTF-8 in all of the traditional APIs and file formats which were compatible with 8-bit extensions of ASCII; which meant that you could migrate to Unicode support without significant changes to APIs and file formats. Also, for text which consists mostly of the ASCII subset, which includes many ASCII-based markup languages, it was much more efficient than UTF-16.
In the early days, however, many languages and systems which adopted Unicode started doing so via UCS-2, and then with the advent of Unicode 2.0 and surrogate pairs, needed to adopt to UTF-16. This was done somewhat inconsistently, and it can cause a lot of pain and confusion.
I've already probably written more than is necessary, so I won't go into the history of each system, but a quick survey of a few popular platforms and languages and their native string encoding:
* C and C++: Support 8-bit unspecified encoding strings (char * , std::string), unspecified width wide characters (wchar_t * , std::wstring, which are 16-bit UTF-16 on Windows and 32-bit UCS-4 on most other platforms), and explicit widths (char8_t * , std::u8string, char16_t * , etc...) which are explicitly UTF-8, UTF-16, and UCS-4.
* Windows uses 16-bit wchar_t * , nominally in UTF-16 but not enforced, as its native string type, and also provides 8 bit APIs with character encoding which can vary at runtime
* Linux and other Unix systems generally use 8-bit char * in an unspecified encoding (which can vary at runtime) as their native string type; most systems these days are using UTF-8 as that 8-bit encoding, but it's not guaranteed
* Java, JavaScript, and C# all use UTF-16 as their native encoding, though in many cases there are still APIs which make most sense for UCS-2 rather than UTF-16.
* Python 2 used unspecified 8-bit encodings for the str type, and a custom encoding that supports all of Unicode for the unicode type. Python 3 changed so that the bytes type was 8-bit with unspecified encoding, and str type was Unicode in a custom encoding; a bytes type alias for str was added to Python 2 to ease the transition, as was a unicode type alias for str in Python 3
* Go and Rust use UTF-8 as their native string types
* Most text-based file formats, such as HTML, have standardized on UTF-8 as the backwards compatibility with ASCII is a big benefit for such formats.
There are a few references on why UTF-8 is generally a better choice for languages and APIs than UTF-16, despite some of the legacy use of UTF-16 in languages and APIs:
string use utf-8, which is 1 byte for the most common characters.
char is unicode
An array of `char` would technically be UTF-32. Which isn't particularly useful, imho.
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.
> 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?
I just want those new to programming to understand the joy of systems and simple graphics programming like in the ol' Turbo Pascal days!
Can someone explain that in basic english?
"I applaud this. And it reminds me of the up-goer five. https://xkcd.com/1133/"
Working link: https://xkcd.com/1133/
It's a lot of fun.