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.

Sign up for GitHub

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

Jump to bottom

DOC: introduce developers convention to use one sentence per line in .md/.rst files #99

Closed
wants to merge 2 commits into from
Closed

DOC: introduce developers convention to use one sentence per line in .md/.rst files #99

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
46ee045
DOC: introduce developers convention to use one sentence per line in …
yarikoptic Nov 3, 2023
3182e49
Wording fixups
yarikoptic Nov 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/40_development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,3 +144,15 @@ dev team sees them. However, these emails arrive with a long, spammy-looking
From address with a Heroku DNS domain; this seems to be an artifact of how
mit.edu processes emails, and does not occur in general (e.g. messages sent
from the API server to users).

### Use a-sentence-per-line formatting in .md/.rst files

One sentence per line should be entered instead of wrapping into paragraphs or making one paragraph per line.
Such a convention is used by a number of projects and advocated by others (see, e.g., [nick.groenen's post](https://nick.groenen.me/notes/one-sentence-per-line/)) since it:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think I will add it here, but found in https://github.com/executablebooks/mdformat/blob/782cb22f294bc4ce48368ee173de4837fc208ecf/docs/users/style.md?plain=1#L159 the quote from "Brian W. Kernighan. "UNIX for Beginners". 1974" which mentions "Start each sentence on a new line.", although in the sample paragraph quoted there this particular sentence doesn't because previous one was wrapped into it already ;-)


- lacks ambiguity on width in case of wrapping into paragraphs
- does not require re-wrapping in case of changing width
- helps to easily identify run-on (too long) sentences
- makes suggestions more to the point (sentence), instead of an entire paragraph if it is in one line

But note, that mass re-formatting of the files which do not yet follow this convention should not be done in conjunction with some other targeted changes.