Every software project should have a Hello World example
It’s not only difficult to use a new language, framework, or library; it’s hard to pick which one you want to use as well. You always need to see code examples so you don’t need to read the source code of whatever you’re using. I’m going to motivate why the simplest example is the first one to show.
For example, when I started a project that required me to parse HTML, I used HTML5Ever since I wasn’t going to write my own HTML parser. I had some difficulties just parsing the HTML and printing it back out. Fortunately, an example that does just this already existed, so after I found it I was about to further modify my program to do useful work.
I submitted a pull request to put this example in the README, and it got accepted, so I’m fairly happy with how easy it is to get started with this project. The example didn’t exactly print “Hello World” but it’s the minimal example that should get you started.
On the other hand, I struggled for a little bit of time with failure
The first example was a bit long and I got lost reading it because I didn’t understand how the library works. If you already know how the library works it’s pretty straightforward, but it is not the SIMPLEST example you can introduce. To make things worse, I got into trouble with the simple.rs example in the examples folder. It reads like this
I’m a big fan of boiling things down to the minimum viable product. I tried to get it down to just one error that prints “Hello World” but with just one, I was running into issues. Turns out, this example actually shows the cause of the error, so it only prints my error which is something that confused me, since I expected it to print my wrapping error as well or instead of my error. The least confusing program is one that just shows the syntax of the library and just prints Hello World since that’s the simplest example you can give.
We made an error and it prints Hello World without muddying the waters with causes. You can always show more examples later that show the proper way of using the library.
This leads me to the Rust front page. You don’t see a single line of code anywhere until you click on something. Even after you click on GET STARTED you don’t see any code until you scroll through installation instructions. I don’t want to install your language yet! I haven’t seen a single example of how it even looks like. The reason given for this is people can’t agree on what example to use. I propose that the Rust home page at the very least has the following example:
it shows the syntax for declaring a function, macro invocation, and a str slice. Even though this exact code is given to you when you call cargo new you STILL want to see it before you even install anything. You can see that this language has braces/semicolons instead of significant whitespace, parentheses for the argument list. It also has precedent in other languages, so there’s no use in bikeshedding this example. If you were to include an editable field and a run button, it would be the perfect.