Formalize language style

[pedzed]

With more contributors, more differences in writing style will become apparent. This issue is a proposal to start a guideline to be able to refer back to for consistent writing.

Most words if not all, seem to use the British style (e.g. -ise endings such as 'finalise'; also used in Australia and New Zealand), to name just one example. One may out of habit (or stubbornness) use US-style. Using US-style could be discussed, but it's important to have agreement upon consistency.

A good example of inconsistent language usage is the usage of "we" and "you":

We can avoid this by using &str instead, and letting &String coerce to a &str whenever the function is invoked.

Source: idioms/coercion-arguments

This pattern is only of interest in Rust. In GC'd languages, you'd take the reference to the value by default (and the GC would keep track of refs), and in other low-level languages like C you'd simply alias the pointer and fix things later.

However, in Rust, we have to do a little more work to do this. An owned value may only have one owner, so to take it out, we need to put something back in

Source: idioms/mem-replace

One could argue that this is done on purpose in this specific instance, but it felt out of place when I read it. But there's also the usage of "me":

The etymology here is unclear to me. The terms 'fold' and 'folder' are used in the Rust compiler, although it appears to me to be more like a map than a fold in the usual sense. See the discussion below for more details.

Source: patterns/fold

Most of the text is also written informally (e.g. 'anyways' over 'anyway') and with abbreviations (in this instance of 'GC', even without explanation).

I am not necessarily suggesting a change and lots of things could be considered gray area (grey area?), but it would be good if there is some writing guideline to be able to refer to when in doubt.

[pedzed]

Does the Rust book have a guideline? It would be wise to use an existing guideline, rather than writing one from start.

[MarcoIeni]

I found this. I think we should link it in the contributing guidelines. Anyway it doesn't address everything you said, but I think we should adhere to the rust book guidelines, without adding extra stuff on top of it if we can. So if you want, you can open an issue similar to this one in the rust-lang/book repo.

[joseluis]

There's also this: https://rust-lang.github.io/api-guidelines/

[MarcoIeni]

There's also this: https://rust-lang.github.io/api-guidelines/

This tells you how to write a rust library. I think this issue is more concerned about writing style.

[joseluis]

This tells you how to write a rust library. I think this issue is more concerned about writing style.

That's true, although it should probably also be taken into account for the code snippets.

[MarcoIeni]

It is a guide about writing libraries, so it doesn't apply to the vast majority of our code snippets. Anyway it's mentioned here.

[MarcoIeni]

Ei pedzed, if you want to have a look I created a PR :)

[simonsan]

I understand some of them, but I would really not start to tell people if they should use American or British English. I'm happy about contributions and I think we should keep in mind that we make it easier for people to contribute than enforce more and more rules. This is still a community made project with international audience and writers. Not everyone speaks native English here, not even us the maintainers. And that's absolutely fine imho. Let's really discuss which rules/directions make sense before applying them to the project and enforcing them on people that are maybe super good programmers and want to participate but are lacking knowledge of all caveats in American English. I'm trying to be inclusive in language styles and people and not exclude more people from writing here indirectly.

[pedzed]

@simonsan It's fine if random contributors do not adhere to the guideline, but in my opinion at least one maintainer must take care that everything is OK before merging to master.

[simonsan]

@simonsan It's fine if random contributors do not adhere to the guideline, but in my opinion at least one maintainer must take care that everything is OK before merging to master.

That is already the case. There is at least one review needed from a code owner to merge PRs and all the CI-tests need to be successful.

[simonsan]

Copied from #201 https://rust-unofficial.github.io/patterns/idioms/mem-replace.html#advantages

Look ma, no allocation! Also you may feel like Indiana Jones while doing it.

I love that actually and I find it kind of what a collaborative book is. Different styles of different authors and not something that is made out of stone and would always sound the same. For sure if it gets too colloquial/informal we can interfere in the PR process, but imho no need to write that down as a rule. I'm trusting the people maintaining this now and in the long-term future that there will be a rational about how a PR/article is written and if it fits to the books style.

---

I'm not against writing a bit more to the guidelines. But I would keep the style and identity of the book visible, so it's clear that it is not written by just one author. It is one of the characteristics of a community-made project that it contains a small mixture of different language style. And I like that about it, honestly. And if there are cases where you for example read something that sounds strange to you there is always the possibility to make a PR and propose and discuss changes.

[MarcoIeni]

I like the informal style, too. And I agree that we shouldn't enforce the style and every author can choose its own, so no "formal" style for me :)

I would really not start to tell people if they should use American or British English.

I understand what you are saying, but there are also people that care about conventions and stuff like this. Let's write an introduction to the style guide, where we make it clear that these rules are not mandatory and that are there just to give generic guidelines. Do you agree simonsan?

[MarcoIeni]

simonsan, in the PR you also mentioned that you prefer British over American English.. As it was described in the PR this decision is done in the rust RFC, it is probably the result of a long debate in the rust community, so I think we have two options:

• say that we SUGGEST to use American English over British, in order to be compliant with the rest of the rust docs
• do not mention American vs British

[simonsan]

simonsan, in the PR you also mentioned that you prefer British over American English..

If it would be important to mention it, I meant.

As it was described in the PR this decision is done in the rust RFC, it is probably the result of a long debate in the rust community, so I think we have two options:

* say that we SUGGEST to use American English over British, in order to be compliant with the rest of the rust docs

* do not mention American vs British

I would not mention any of them, we could mention that we write our articles in English if that would be sufficient, but I guess that would be already clear from the book itself. So maybe not mentioning it would be sufficient then?

[MarcoIeni]

So maybe not mentioning it would be sufficient then?

I understand the reasons behind your position :)

Is it ok for you if we leave the link to the RFC there and we delete the entry from the "tldr"?

[simonsan]

So maybe not mentioning it would be sufficient then?

I understand the reasons behind your position :)

Is it ok for you if we leave the link to the RFC there and we delete the entry from the "tldr"?

Sure, if people read it and adhere to that style I think no one will tell them: "No, you need to write that different! 😠 " :P But I would just not keep it directly in here and enforce it with power in a PR, I think you know how I mean it. ;)

[MarcoIeni]

Sure I agree with you :)

I will work on the introduction.

[MarcoIeni]

pedzed, regarding style issues you have found, feel free to add PR for those if you want :)