rust-unofficial / patterns

A catalogue of Rust design patterns, anti-patterns and idioms
https://rust-unofficial.github.io/patterns/
Mozilla Public License 2.0
7.87k stars 357 forks source link

Prepare the book to be included as rust book #199

Closed pickfire closed 3 years ago

pickfire commented 3 years ago

Should we try preparing the book to be included as part of the rustup install or maybe we shouldn't do it? Rust API Guidelines isn't there as well but I wonder if it would be good to have both taken in at the same time? This allows people to read it offline and while having it bundled with the official docs, but of course the quality needs to be there first (maybe the team needs to review). Or maybe we could take the first them by creating a rustup component?

MarcoIeni commented 3 years ago

Or maybe we could take the first them by creating a rustup component?

I think it is better we wait for someone to ask us to do the job, instead of doing it and finding out we wasted our time.

Furthermore this is not an official book yet, as it belongs to rust-unofficial and not to rust-lang github organization.

the quality needs to be there first

Yes, let's continue to work on this book. People can still download it, build it and read it offline anyway :)

KodrAus commented 3 years ago

This is a really interesting idea 🤔

I'm actually not sure what the bar for introducing new content into rustup is, but at some point in the future it would be great to look into.

simonsan commented 3 years ago

There is currently a proposal going on to bring this book into rust-lang and put it nearer to the API-Guidelines with exchange of discussion in that regard. There might be a Patterns and Guidelines project group as well. As it's a developing story I can't really say much more concrete things. For now this topic here is out of scope imho and the focus should stay on bringing more patterns and information into the book.

7596ff commented 3 years ago

I've been reading through this since seeing it on reddit and I'm noticing some bad choices in vernacular. Two specifically are the use of the terms "tribal knowledge" and "dummy function". If it's welcome I would like to comb through the text and rewrite these sorts of things. Not looking to start any wars here, just a suggestion.

fade2black commented 3 years ago

For now this topic here is out of scope imho and the focus should stay on bringing more patterns and information into the book. (@simonsan )

As for anti_patterns, refactoring.. what is the main focus? For example, there are antipatterns language independent, code smells, etc. Or should we focus only on idioms, patterns, antipatterns Rust specific?

simonsan commented 3 years ago

I've been reading through this since seeing it on reddit and I'm noticing some bad choices in vernacular. Two specifically are the use of the terms "tribal knowledge" and "dummy function". If it's welcome I would like to comb through the text and rewrite these sorts of things. Not looking to start any wars here, just a suggestion.

For sure, feel free to make a PR, it's appreciated.

simonsan commented 3 years ago

For now this topic here is out of scope imho and the focus should stay on bringing more patterns and information into the book. (@simonsan )

As for anti_patterns, refactoring.. what is the main focus? For example, there are antipatterns language independent, code smells, etc. Or should we focus only on idioms, patterns, antipatterns Rust specific?

I think the scope is really rust-lang itself. So people switching from other languages or people learning the language new have something at hand to deal with common software design principles in an idiomatic way. Starting with things that are already on that list might be a good start. Everyone can always add things to the list by stating ideas in an issue or in a discussion.

What do you think yourself? Is that viable? Other ideas?

fade2black commented 3 years ago

@simonsan

What do you think yourself? Is that viable? Other ideas?

Yeah, I agree. Everything we explain here should be linked to rust-lang somehow. For example, if we explain a pattern we should focus on how it is implemented particularly in rust-lang, and how it is used in rust-lang.

Especially I'd like to pay special attention to idioms. People coming from other languages, say C/C++, with high probability already know about design patterns and how and when to apply them, but the have difficulties how to translate those ideas into rust-lang. For example, I, myself, went through this last time we were working on the Strategy patterns; a lot of suggestions to correct source code mainly translating the code into idiomatic way. The bottomline, we should focus on "HOW IN RUST" part of our text. For example, how to do this pattern IN RUST, how to avoid antipattern IN RUST, ...etc.

simonsan commented 3 years ago

For example, I, myself, went through this last time we were working on the Strategy patterns; a lot of suggestions to correct source code mainly translating the code into idiomatic way. The bottomline, we should focus on "HOW IN RUST" part of our text. For example, how to do this pattern IN RUST, how to avoid antipattern IN RUST, ...etc.

I agree, but from my point of view I already focused on this, do you think this isn't stated as clear as it could be somewhere in the Readme.md, contribution guide or so? If so, may you want to fix it and make a PR? Because it could be that I'm a bit blind to this. I tried to state explicitly in the contribution guide for example, that it should be written in an idiomatic rust way and explain the topics on a level experts and rustlings can understand and learn.

fade2black commented 3 years ago

@simonsan The first sentence in the README.md says

An open source book about design patterns and idioms in the Rust programming language that you can read here.

I think this is enough. In any case, reviewers does their job very well by providing feedbacks and suggestions😊

MarcoIeni commented 3 years ago

I am closing this issue, since there is nothing we can do to solve this, except solving all the other issues of this repo basically :) Feel free to comment if you think that further discussion is needed. In this case we can open this issue again.