One sentence per line

When writing source documentation in a format such as Markdown, reStructuredText or AsciiDoc, I recommend you place every sentence on its own line and don’t use fixed-column word-wrapping.


  • It prevents reflows (meaning a change early in the paragraph won’t cause the remaining lines in the paragraph to reposition), which ensures code diffs look more clean.
  • It lets you swap sentences more easily.
  • It lets you separate and join paragraphs more easily.
  • It lets you comment out sentences or add commentary to them.
  • You can spot sentences which are too long or sentences that vary widely in length.
  • You can spot redundant (and thus mundane) patterns in your writing.
  • You can easily apply bulk actions on sentences with editor macros, such as converting to list items by prepending a dash to each line.
  • It improves using GitHub’s “suggest changes” workflow, as it lets your reviewer start a new suggestion for each sentence instead of having to combine them.