💾 Archived View for gemini.rfmpie.com › posts › semantic-line-breaks captured on 2023-07-22 at 16:37:08. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2022-03-01)
-=-=-=-=-=-=-
(I ported this old post from my blog, cleaned it up, and backdated it. I'm going to refer to it soon from Gemini space.)
When I joined Squarespace and went to contribute to my team's Markdown docs, I saw that they often looked like this:
---
These are our docs.
There is a line break after every sentence,
and sometimes there are line breaks after commas.
This is another paragraph.
And so on....
---
I initially assumed this was due to ... sloppiness? I didn't know. Through code review, I discovered that this was a deliberate use of semantic line breaks.
https://rhodesmill.org/brandon/2012/one-sentence-per-line/
At first, I bristled. Our justification seemed to be that our old version of Bitbucket didn't support word wrap in diffs. Long lines would just run off the page, making code review obnoxious. I recoiled at the notion of making our docs source look weird just to compensate for old Bitbucket's diff UI. If we want docs to feel good, we should make them look good!
Fast forward a few months, and I have seen the light: semantic line breaks are great with version control, and I now try to use them whenever I can. Instead of managing your changes one paragraph at a time, you can manage them one thought at a time. This works especially well when operating on your git changes in hunks, as I try to do.
It’s so tempting to rush to judgment when your opinions are challenged. In this case, my opinions were flimsy and my judgment premature. I should have been curious first!