Description
I propose that rustc dev guide move to semantic line breaks. Essentially, this means one sentence per line.
When writing prose in a structured format like Markdown in a version control system, diffs can easily become difficult to read or even useless. Separating each sentence with a new line makes it easy to parse diffs with the human eye.
Diff without semantic linefeeds:
-Rust is awesome. It has a great community. You can help improve Rust by contributing to rustc. Don't be scared!
+Rust is awesome. It is supported by a great community. You can help improve Rust by contributing to the Rust compiler. Don't be scared!Diff with semantic linefeeds:
Rust is awesome.
-It has a great community.
+It is supported by a great community.
-You can help improve Rust by contributing to rustc.
+You can help improve Rust by contributing to the Rust compiler.
Don't be scared!This makes later reviewing a breeze!
If a sentence goes over, say 100 characters, it should either be:
- split into two or more sentences, or
- split along multiples lines at some semantically meaningful point (a comma, conjunctions, colon, etc.).
Large documentation projects that use this convention are more intuitive to work on and review. I believe it makes for better writing as well.
This wouldn't have to be a hard requirement. Since most edits already touch multiple lines, using this convention would only add a small initial burden for reviewers. Over time, the guide will become easier to work with and review.