
The Rust Libs Blitz - aturon
https://blog.rust-lang.org/2017/05/05/libz-blitz.html
======
dmix
This is something Haskell could really benefit from. Largely just through
writing documentation for common libraries.

A post was recently on the frontpage of HN about using Haskell in production
[1] that divided the common documentation experience between "hard" and "soft"
docs. Far too often with Haskell you only get the 'hard' docs where you get
descriptions of functionality and functions but it lacks why (and cohesively
how) you would want to use the various functionality.

This makes a strong assumption you are already deeply familiar with the
usecase and implementation concept.

This may apply to Rust as well. Rust will likely attract experienced
developers, much like Haskell, where in most cases a decent level of code
quality would be anticipated. But one of the hardest things to get right as an
OSS developer is documentation. You're often so busy with the burden of
maintenance that the explanatory side gets sidelined. Especially as a library
and the underlying language evolves. So I hope this is a priority focus during
their reviews.

[1]
[https://news.ycombinator.com/item?id=14266462](https://news.ycombinator.com/item?id=14266462)

~~~
derefr
I've seen this problem in the Elixir library ecosystem as well. Regardless of
the package, people _do_ see the value in contributing to the commons with PRs
for "hard docs" (because they themselves will probably need to read them again
later, and don't want to get tripped up _again_ by reading false docs.) But
nobody wants to contribute "soft docs" to anything but the language core.

It feels like the real issue is that anyone who considers themselves a writer,
as well as a programmer, tends to have a blog; and that people who have blogs
are incentivized to write "soft docs" as tutorial blog posts _for_ their
blogs, instead of as encyclopedia-style or cookbook-style additions to the
given library's docs.

I wonder if a programming language could adopt a Code of Conduct discouraging
tutorial blog-posts in favor of soft-doc PRs...

~~~
sotojuan
Soft docs are harder and take longer, and as said elsewhere are not
appreciated enough. If I'm writing an Elixir library for (what I think) my own
use, I'll stop at typespecs, docstring with an example, and a short
description.

I'll only start doing the tutorial doc and/or blog post if others have
interest in the library. There's just not enough time :/

~~~
derefr
The thing is, it's not that there aren't a lot of blog posts. There are!
There's usually at least one blog post about any library I care to use. But
it's _only_ a blog post—it's something someone wrote at some point—and so it's
not corrected for misapprehensions the author (who is usually not the author
of the library) had about the idiomatic way to use the library, nor is it kept
up to date with changes in the library like soft docs would be.

I don't think there's a dearth of people willing to write blog posts. There's
just a dearth of people willing to do the equivalent job to what Wikipedia
editors do for general-purpose articles: collating those "primary sources"
into a single, coherent, up-to-date overview.

------
z1mm32m4n
I really love seeing articles like this come out about Rust.

It's language design the way it should be: incorporating the cutting edge
ideas from academia while still striving to cater to beginners; drawing on the
strengths of other languages communities to build out good library and
solutions to package management; designing everything in the open, and
constantly seeking feedback from their users.

It's a great blend of theoretical CS, HCI, computer systems, and application
development, and it's always fun to hear about what they're up to.

~~~
newsat13
> I really love seeing articles like this come out about Rust.

Yeah, me as well. It's a perfect marriage of academic know how and pragmatism.
Very exciting year for Rust.

------
kibwen
I'm going to use this opportunity to second the suggestion that people
consider taking this year's Rust community survey: [https://blog.rust-
lang.org/2017/05/03/survey.html](https://blog.rust-
lang.org/2017/05/03/survey.html) . I know it's mentioned in the post, but I
figure the number of people reading the comments is much larger than the
number who actually click through the link. :P And even if you don't or have
never used Rust, we still value your feedback!

~~~
seeekr
heads up: On page 15 it feels like the questions are not written from a user-
centric point of view any more, while the previous ones were excellent. "The
Rust project" has an unclear or at least less significant meaning to me as a
user than probably to someone working on increasing Rust adoption, which I
gather the first 2 questions on p. 15 are about? ("Rust project" could also
mean "that thing you're working on using Rust", to me as user/dev. Usually you
folks call it "Rust language" or something with "community" etc.) Great survey
otherwise, just about to finish it!

------
mintplant
May I suggest the bytes crate [0]? It's one of those small libraries providing
a key building block (mutable and immutable byte buffers), and is a dependency
of tokio-io and any other crate which implements tokio-io's Encoder/Decoder
traits.

[0] [https://crates.io/crates/bytes](https://crates.io/crates/bytes)

~~~
brson
Yes, thank you for the suggestion. I agree that's a good candidate and will
note it on thread.

------
ssdfe
I do wish cargo packages were namespaced a la Github. Squatting on usernames
is one thing, but package and project names are often the only way you hear
about something. cargo react-svg might be a terrible project or a good quality
one maintained by facebook, but you wouldn't know from the name. Because of
the name, it'll be at least somewhat downloaded if that's a common need. It
makes grouping by org difficult too.

~~~
MoSal
I wrote cargo-esr[1], an alternative tool for searching crates, with the
purpose of narrowing down good choices.

Feedback welcome.

[1] [https://github.com/rust-alt/cargo-esr](https://github.com/rust-alt/cargo-
esr)

------
eriknstr
The article also links the state of rust survey. I visited the survey with
intent to answer it but the first question "Do you use Rust?" only has the
following three alternatives for an answer:

\- "Yes"

\- "No, I stopped using Rust"

\- "No, I've never used Rust"

When making a survey the alternatives for the answers are very important. I
feel that none of these alternatives apply to me. That's bad. Unfortunate
because I would have liked to participate in the survey.

I've done a little bit of beginner programming in Rust in order to try and
learn the language. However I haven't yet used it to implement anything
actually useful so I wouldn't say "yes, I use Rust". It's been a while since
last I did something in Rust but I wouldn't say "no, I stopped using Rust"
because to me that implies that I have decided that Rust is not for me, which
is not something that I feel, I want to use it, I just keep pushing it down on
the list of things to do because other more immediate desires and problems
keep popping up.

~~~
seqastian
So, just take YES and move on? Surveys are about trends not about absolutes.

~~~
emmelaich
I'm in the same boat but answered no. I'll go with the grandparent coment and
suggest that an option indicating that you've tinkered and dabbled with it and
no more. (Sorry, a more appropriate wording doesn't come to mind at the
moment)

~~~
divs1210
> i use it in production > i use it for hobby projects > i have played with it
> > i have never used it

Clojure survey had something along these lines

------
stcredzero
_There’s a countervailing mindset which, in its harshest terms, says “the
standard library is where code goes to die”_

This can be addressed in a language with sufficient annotation and good parser
tools. In some future language, there should be a unification between the
version control, the de-facto codesharing site, language/library versions, and
syntax-driven tools to automatically rewrite code.

It should be possible to "publish" a language and its libraries such that any
breaking changes will automatically be updated when you switch library
versions. (This should also be applicable to Entity-Relation diagrams and
Object-Relational mappings -- those can be treated as a versioned library.)

~~~
skybrian
The problem is that the number of possible combinations of versions grows
rapidly as you add versions. This makes testing harder, as it spreads the
community thin - everyone's using a different combo than everyone else.

To avoid that, you need to standardize on a blessed set of versions to be
tested together, much like assembling a release of a Linux distro.

People will still swap in alternate versions of libraries occasionally, but
keeping things mostly standard and a few cherry-picks is still better than
everyone choosing differently.

~~~
stcredzero
_The problem is that the number of possible combinations of versions grows
rapidly as you add versions._

The point is not to let people hang out in whatever obscure snowflake version-
set they want to. The point is to make migration going forward as painless as
possible. However, that expectation is not so much about the tooling as it is
about the developer/language community.

 _To avoid that, you need to standardize on a blessed set of versions to be
tested together, much like assembling a release of a Linux distro._

Yes, there should be this! However, you will still have some stragglers and
outliers -- this is what the historical reality shows us. The point of such
tooling is precisely to minimize the pool of stragglers, not to maximize them!

------
wyldfire
> The product of this process will be a mature core of libraries together with
> a set of API guidelines that Rust authors can follow to gain insight into
> the design of Rust and level up crates of their own interest.

Is there a plan to make these things statically checkable by
rustc/rustfmt/rust-tidy or some sort?

~~~
dtolnay
Yes! The statically checkable ones will be checked by rustc or Clippy. Though
some of the guidelines are at a higher level than what those would be able to
check. For example: rustc wouldn't be able to tell whether a particular one of
your traits would be valuable to make accessible as a trait object.

~~~
ronjouch
Beginner question: what would make a crate _non_ -statically-checkable?

~~~
Manishearth
A guideline like "your tests should test all major functionalities of an API"
can't be statically checked for example.

It's not about the crate being non checkable, it's about the check being
something that needs a human to look at.

~~~
moosingin3space
I realize that statically checking for tests is reducible to the halting
problem, but would it be possible to have some sort of code-coverage checker
that would make sure all externally-facing functions have non-zero coverage?
That could be used to construct a checklist for a library developer.

~~~
kilotaras
Code coverage in itself isn't a very useful metric. Classic example is big
test with no asserts will get you pretty good coverage.

There's a rather computationally intensive technique called mutation testing
where you introduce bugs into code (e.g. change + to -, flip conditionals,
etc.) and check that tests fail.

~~~
burntsushi
Code coverage has been useful to me in practice, so I think blanket statements
like "code coverage isn't useful" is very misleading. For example, code
coverage has helped me identify specific branches in my code that are
untested, which in turn help guide me to write additional unit tests.

You don't need to completely dismiss other testing techniques. Mutation
testing can be useful at the same time that code coverage is useful.

~~~
yazaddaruvala
Totally agreed. Branch coverage has been far more useful to me than line
coverage has.

------
bpicolo
One thing I don't see here: It's difficult to integrate libs into e.g.
parallel when they don't derive all the various things (Copy). Will a goal be
to aim for deriving standards for libs looked at?

~~~
no_protocol
It's part of the checklist:

[https://github.com/brson/rust-api-
guidelines#interoperabilit...](https://github.com/brson/rust-api-
guidelines#interoperability)

Maybe the checklist should get a more prominent link or notice in the blog
post. It took me a while to find it.

~~~
bpicolo
Ah cool, thanks for the link.

------
bhickey
bstrie is coming by my place tomorrow, we're going to take a stab at
overhauling `rand`. We must've been discussing this for two years.

~~~
brson
Oh great. Keep us updated.

------
dasmoth
I realise this is being done with the best of intentions and will probably be
a big net positive in practise, but something about the way it has been
presented here rubs me up the wrong way.

In short, the blog post makes very little mention of the role of the primary
_author(s)_ of the libraries in question, beyond "Every two weeks, hold a
library team meeting [...] with the author in attendance." While I imagine the
reality will be quite different, this sounds an awful lot like "oi, you, code
review in my office _now_!"

One of the attractions of working on open source is that it offers more scope
for autonomy and individual recognition than the typical commercial software
job. It's slightly alarming that this doesn't seem to be recognised here.

As I say, I'm sure the reality will be fine (and I remain very keen to give
Rust a serious try when time permits), but the rather collectivist
presentation here is a tiny bit off-putting.

~~~
steveklabnik
Most of the crates being focused on are either maintained by the libs team
already, or are authored by a member of the libs team. It turns out that the
people on the libs team have written a lot of widely used and pretty solid
libraries ;)

Nobody is forcing stuff on random crate authors; if they didn't want to
participate, then that's 100% okay.

~~~
dasmoth
Thanks, that puts a slightly different perspective on things!

I still feel there's a slightly-unfortunate ambiguity in the linked
announcement post, though.

~~~
steveklabnik
Totally, I hear you. It can be tough from both sides, that is, to people super
heavily involved in Rust, they know these names, so the fact is obvious. So it
doesn't get written down, and then when people from _outside_ of living and
breathing Rust every day read it, they don't have the context.

Words are hard.

------
Animats
Does the "Rust standard of quality" for these crucial crates include "no
unsafe code"?

"Vec" currently needs unsafe code, because Rust doesn't have the expressive
power to talk about a partially initialized array. Everything else with unsafe
code is an optimization. Often a premature one. Maps should be built on "Vec",
for example.

~~~
eximius
In Rust, 'unsafe code' is really 'partially compiler check exempt'. It does
not mean the code is unsafe. You can manually verify the 'unsafe' parts.

It is very unfortunately named.

~~~
hyperpape
It's unsafe in roughly the same way that Rust developers call C and C++
unsafe, right? The advantage is that it's a special, relatively uncommon mode,
and it's explicitly marked. But I don't think you can minimize the reality
that it's unsafe without also minimizing one of the major selling points of
the language.

~~~
epage
Because only 10% of your code isn't verified by the compiler but instead needs
extra review and tests doesn't eliminate the benefit that 90% of your code is
verified by the compiler.

------
jhasse
My biggest gripe with the crate situation is that some of them require
nightly. E.g. everything coroutines AFAIK.

~~~
Manishearth
The coroutine libraries are the codegen ones, yes?

Coroutines are kinda more like a language feature that people have hacked
libraries to do codegen for instead, so IMO it's pretty understandable that it
needs nightly.

Many of these libraries are prototyping designs that will eventually be
proposed as part of the language.

~~~
moosingin3space
Since Rust 1.15, most libraries that require nightly seem to be this kind of
prototyping, at least to my eye.

------
microcolonel
Rust sorta has a de-facto code style. It'd be interesting to add tooling to
cargo to make it obvious how to comply with the evolved standard style for
Rust.

~~~
hackcrafter
There is definitely a changing Rust definition of good code hygiene in terms
of how to write code in the most "Rustic" way, but in terms of code
formatting, there is already rustfmt[0]

[0] [https://github.com/rust-lang-nursery/rustfmt](https://github.com/rust-
lang-nursery/rustfmt)

------
modeless
Unfortunate name. I thought this was about libz aka zlib.

~~~
AndyKelley

        andy@xps ~> python3
        >>> "Libz" == "libz"
        False

~~~
mrob

        >>> title_case("Libz") == title_case("libz")
        True

~~~
AndyKelley
touché

------
luck_fenovo
It is an unfortunate name. I don't know why, given how inclusive the Rust
community usually is and how eager they were to remove master/slave
terminology, that they would choose to announce this effort under the banner
of Nazi war tactics.

~~~
dang
Please don't do this here.

We detached this subthread from
[https://news.ycombinator.com/item?id=14275990](https://news.ycombinator.com/item?id=14275990)
and marked it off-topic.

