bevy/.github/contributing/engine_style_guide.md

# Style guide: Engine

## Contributing

For more advice on contributing to the engine, see the [relevant section](../../CONTRIBUTING.md#Contributing-code) of `CONTRIBUTING.md`.

## General guidelines

1. Prefer granular imports over glob imports like `bevy_ecs::prelude::*`.
2. Use a consistent comment style:
   1. `///` doc comments belong above `#[derive(Trait)]` invocations.
   2. `//` comments should generally go above the line in question, rather than in-line.
   3. Avoid `/* */` block comments, even when writing long comments.
   4. Use \`variable_name\` code blocks in comments to signify that you're referring to specific types and variables.
   5. Start comments with capital letters. End them with a period if they are sentence-like.
3. Use comments to organize long and complex stretches of code that can't sensibly be refactored into separate functions.
4. When using [Bevy error codes](https://bevyengine.org/learn/errors/) include a link to the relevant error on the Bevy website in the returned error message `... See: https://bevyengine.org/learn/errors/b0003`.

## Rust API guidelines

As a reference for our API development we are using the [Rust API guidelines][Rust API guidelines]. Generally, these should be followed, except for the following areas of disagreement:

### Areas of disagreements

Some areas mentioned in the [Rust API guidelines][Rust API guidelines] we do not agree with. These areas will be expanded whenever we find something else we do not agree with, so be sure to check these from time to time.

> All items have a rustdoc example

- This guideline is too strong and not applicable for everything inside of the Bevy game engine. For functionality that requires more context or needs a more interactive demonstration (such as rendering or input features), make use of the `examples` folder instead.

> Examples use ?, not try!, not unwrap

- This guideline is usually reasonable, but not always required.

> Only smart pointers implement Deref and DerefMut

- Generally a good rule of thumb, but we're probably going to deliberately violate this for single-element wrapper types like `Life(u32)`. The behavior is still predictable and it significantly improves ergonomics / new user comprehension.

[Rust API guidelines]: https://rust-lang.github.io/api-guidelines/about.html
Comprehensive CONTRIBUTING.md (#2040) [RENDERED](https://github.com/alice-i-cecile/bevy/blob/better-contributing/CONTRIBUTING.md) Improves #910. As discussed in #1309, we'll need to synchronize content between this and the Bevy website in some way (and clean up the .github file perhaps?). I think doing it as a root-directory file is nicer for discovery, but that's a conversation I'm interested in having. This document is intended to be helpful to beginners to open source and Bevy, and captures what I've learned about our informal practices and values. Reviewers: I'm particularly interested in: - opinions on the items What we're trying to build, where I discuss some of the project's high-level values and goals - more relevant details on the `bevy` subcrates for Getting oriented - useful tricks and best practices that I missed - better guidance on how to contribute to the Bevy book from @cart <3 2021-08-14 19:21:36 +00:00			`# Style guide: Engine`

Added API guidelines to CONTRIBUTING.md (#3646) Closes #3497. I added the rust API guidelines (https://rust-lang.github.io/api-guidelines/about.html) to the `CONTRIBUTING.md` file. ## Note As noted in #3497 we should note any areas where we deliberately disagree as they arise. If we start adding these areas it might be a good idea to remove the mention of the `API guidelines` in the `CONTRIBUTING.md` file and move it to the `engine_style_guide.md`. That way we still have the connection between the `CONTRIBUTING.md` and the `API guidelines`, but we have more "space" to work with and can go into more detail about what we agree and disagree on. For now I would leave it this way, because it's one less click to get to the guidelines. Co-authored-by: KDecay <KDecayMusic@protonmail.com> 2022-01-16 02:40:25 +00:00			`## Contributing`

Fix broken link between files (#10962) # Objective - Fix a link to a non-existent section of a document. ## Solution - Change the link to a more likely source. 2023-12-13 18:46:44 +00:00			For more advice on contributing to the engine, see the [relevant section](../../CONTRIBUTING.md#Contributing-code) of `CONTRIBUTING.md`.
Added API guidelines to CONTRIBUTING.md (#3646) Closes #3497. I added the rust API guidelines (https://rust-lang.github.io/api-guidelines/about.html) to the `CONTRIBUTING.md` file. ## Note As noted in #3497 we should note any areas where we deliberately disagree as they arise. If we start adding these areas it might be a good idea to remove the mention of the `API guidelines` in the `CONTRIBUTING.md` file and move it to the `engine_style_guide.md`. That way we still have the connection between the `CONTRIBUTING.md` and the `API guidelines`, but we have more "space" to work with and can go into more detail about what we agree and disagree on. For now I would leave it this way, because it's one less click to get to the guidelines. Co-authored-by: KDecay <KDecayMusic@protonmail.com> 2022-01-16 02:40:25 +00:00
			`## General guidelines`
Comprehensive CONTRIBUTING.md (#2040) [RENDERED](https://github.com/alice-i-cecile/bevy/blob/better-contributing/CONTRIBUTING.md) Improves #910. As discussed in #1309, we'll need to synchronize content between this and the Bevy website in some way (and clean up the .github file perhaps?). I think doing it as a root-directory file is nicer for discovery, but that's a conversation I'm interested in having. This document is intended to be helpful to beginners to open source and Bevy, and captures what I've learned about our informal practices and values. Reviewers: I'm particularly interested in: - opinions on the items What we're trying to build, where I discuss some of the project's high-level values and goals - more relevant details on the `bevy` subcrates for Getting oriented - useful tricks and best practices that I missed - better guidance on how to contribute to the Bevy book from @cart <3 2021-08-14 19:21:36 +00:00
Clean up advice on glob imports in style guide (#4644) # Objective - Example was misleading, as we never import `bevy` itself in the engine (except in integration tests). ## Solution - Clean up wording. ## Context Noticed by @mockersf in #4608. 2022-05-02 18:45:00 +00:00			1. Prefer granular imports over glob imports like `bevy_ecs::prelude::*`.
Comprehensive CONTRIBUTING.md (#2040) [RENDERED](https://github.com/alice-i-cecile/bevy/blob/better-contributing/CONTRIBUTING.md) Improves #910. As discussed in #1309, we'll need to synchronize content between this and the Bevy website in some way (and clean up the .github file perhaps?). I think doing it as a root-directory file is nicer for discovery, but that's a conversation I'm interested in having. This document is intended to be helpful to beginners to open source and Bevy, and captures what I've learned about our informal practices and values. Reviewers: I'm particularly interested in: - opinions on the items What we're trying to build, where I discuss some of the project's high-level values and goals - more relevant details on the `bevy` subcrates for Getting oriented - useful tricks and best practices that I missed - better guidance on how to contribute to the Bevy book from @cart <3 2021-08-14 19:21:36 +00:00			`2. Use a consistent comment style:`
			1. `///` doc comments belong above `#[derive(Trait)]` invocations.
			2. `//` comments should generally go above the line in question, rather than in-line.
			3. Avoid `/* */` block comments, even when writing long comments.
			4. Use \`variable_name\` code blocks in comments to signify that you're referring to specific types and variables.
			`5. Start comments with capital letters. End them with a period if they are sentence-like.`
			`3. Use comments to organize long and complex stretches of code that can't sensibly be refactored into separate functions.`
Fixed #14248 and other URL issues (#14276) # Objective Fixes #14248 and other URL issues. ## Solution - Describe the solution used to achieve the objective above. Removed the random #s in the URL. Led users to the wrong page. For example, https://bevyengine.org/learn/errors/#b0003 takes users to https://bevyengine.org/learn/errors/introduction, which is not the right page. Removing the #s fixes it. ## Testing - Did you test these changes? If so, how? I pasted the URL into my address bar and it took me to the right place. - Are there any parts that need more testing? No 2024-07-11 12:01:49 +00:00			4. When using [Bevy error codes](https://bevyengine.org/learn/errors/) include a link to the relevant error on the Bevy website in the returned error message `... See: https://bevyengine.org/learn/errors/b0003`.
Added API guidelines to CONTRIBUTING.md (#3646) Closes #3497. I added the rust API guidelines (https://rust-lang.github.io/api-guidelines/about.html) to the `CONTRIBUTING.md` file. ## Note As noted in #3497 we should note any areas where we deliberately disagree as they arise. If we start adding these areas it might be a good idea to remove the mention of the `API guidelines` in the `CONTRIBUTING.md` file and move it to the `engine_style_guide.md`. That way we still have the connection between the `CONTRIBUTING.md` and the `API guidelines`, but we have more "space" to work with and can go into more detail about what we agree and disagree on. For now I would leave it this way, because it's one less click to get to the guidelines. Co-authored-by: KDecay <KDecayMusic@protonmail.com> 2022-01-16 02:40:25 +00:00
			`## Rust API guidelines`

			`As a reference for our API development we are using the [Rust API guidelines][Rust API guidelines]. Generally, these should be followed, except for the following areas of disagreement:`

			`### Areas of disagreements`

			`Some areas mentioned in the [Rust API guidelines][Rust API guidelines] we do not agree with. These areas will be expanded whenever we find something else we do not agree with, so be sure to check these from time to time.`

			`> All items have a rustdoc example`

			- This guideline is too strong and not applicable for everything inside of the Bevy game engine. For functionality that requires more context or needs a more interactive demonstration (such as rendering or input features), make use of the `examples` folder instead.

			`> Examples use ?, not try!, not unwrap`

			`- This guideline is usually reasonable, but not always required.`

			`> Only smart pointers implement Deref and DerefMut`

			- Generally a good rule of thumb, but we're probably going to deliberately violate this for single-element wrapper types like `Life(u32)`. The behavior is still predictable and it significantly improves ergonomics / new user comprehension.

			`[Rust API guidelines]: https://rust-lang.github.io/api-guidelines/about.html`