Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tracking issue: semantic line breaks #1241

Closed
pierwill opened this issue Oct 28, 2021 · 1 comment
Closed

Tracking issue: semantic line breaks #1241

pierwill opened this issue Oct 28, 2021 · 1 comment

Comments

@pierwill
Copy link
Member

pierwill commented Oct 28, 2021

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:

  1. split into two or more sentences, or
  2. 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.

@JohnTitor
Copy link
Member

This is a duplicate of #1132, could you reuse that issue?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants