Add advice on semantic line breaks to CONTRIBUTING.md

[alice-i-cecile]

How can Bevy's documentation be improved?

Breaking your lines after each sentence / clause is useful for reviewers and should be the default style for both doc comments and markdown.

To be specific:

1. It makes the git history more reflective of the actual changes.
2. It's much easier to insert (and read) suggestions on Github.
3. It's easier to identify violations of markdownlint on smaller lines.

I find text broken in this way to be much easier to read and understand, but others feel the opposite way :p

We should add a link to the semantic line breaks document to the CONTRIBUTING.md section on docs.

[Nilirad]

The PR should also edit rustfmt.toml:
it should remove the commented lines for comment formatting.

[mockersf]

I'm not sure I agree for doc comments. While they'll be rendered as markdown on rustdoc where it won't matter, they'll also be read in code where this may look strange.

[Nilirad]

By personal experience I can say that there is a net improvement in using semantic line breaks in doc comments. Also, I did not feel any degradation of experience while reading the raw comments

[nicopap]

I was originally dubious of this proposition, but after having done my own research I agree this would be a good idea.

One suggestion though: remind that 1 sentence (or less) per line should not go beyond 100 columns. It's possible to split the sentence when they get longer, and that should be reminded.

Here is more discussion on the topic:

• https://sive.rs/1s
• https://news.ycombinator.com/item?id=31808093

[Nilirad]

One suggestion though: remind that 1 sentence (or less) per line should not go beyond 100 columns. It's possible to split the sentence when they get longer, and that should be reminded.

That's a less restrictive version of point 12 of semantic line breaks. I may like it, since 80 characters are quite low. That being said, if each logical chunk of a sentence has its own line, the 80 character limit becomes more reasonable.

[nicopap]

For method docs, you only have 92 characters left for doc comment (indent + /// ) while for module-level items, you have 96. I'm in favor of 80 character lines for docs, but I think the difference between 92 and 80 is not that significant.

[Nilirad]

Yeah, I was confusing columns vs characters lol.
I think there is still very little difference between 80, 92 or 96 characters when we are talking about recommendations, and not hard rules.