At the moment most of our documentation files (*.rst) try to uphold 80 column limit specified in the coding standard with varying degree of success. Most of the violations come from links and code blocks. Some files, like LibASTImporter.rst, don’t even bother, instead following one line per sentence approach.
Upholding 80 column limit involves a significant amount of reflowing, especially when editing existing documentation. In the worst case, insertion of just couple of words at the beginning of a paragraph results in reflow changes until the end of the paragraph, increasing amount of work for PR author, distracting reviewers from the actual change, and polluting git blame output.
I propose to remove 80 column limit, possibly in favor of something like one sentence per line approach that LibASTImporter.rst uses. In various use cases where display width is limited, automatic word wrap should be good enough (which is not necessarily the case for source code).
Update: initially this was proposed for Clang, but following positive feedback from Renato and Nikita, I’m proposing this for the entire LLVM project.
Should reflow to a particular width be required for documentation files?
Yes, current limit of 80 columns is good
Yes, but we need to change the column limit
No, one line per paragraph
No, one line per sentence
No, one line per part of sentence (split by punctuation)
Years ago, @davidchisnall had a great reason why this is preferred: “It’s a lot easier to review sentence changes that way”. Line-break in text is semantically meaningless.
+1 to this approach for documentation files. Having “semantic line breaks” (one sentence per line) is so much more pleasant to review and reason about, so long as the rendering remains the same for the final output.
Following positive feedback from outside of Clang, I moved this thread to “LLVM Project” category, and now this is proposed for the entire LLVM project.
This is not related, but is there any policy on trailing whitespace in documentation files? If not, could we require adhering to the no-trailing-whitespace rule even though the 80-column rule doesn’t apply?
But could we still have some reasonable limit to refer to during code reviews (e.g. 120 chars)?
I’d rather want 2 lines with 80 + 70 symbols each (with a break between words) instead of one long 150-symbol line.
Having a sensible limit will also allow us (clang-tidy devs) to continue using doc8 linter for .rst files which will warn on inadequate long lines and still make exception for links that can’t be broken into multiple lines.
All the arguments I presented against having 80 column files are applicable to any column limit. Reviewers can use automatic word wrapping, which should do a good job for plain text.
I like this proposal.
I’m wondering if there would be value in some kind of style guide to encourage not using overly long sentences.
I find that the first time I type out a thought, I often type a long sentence.
On second reading, I often “refactor” my long sentence into 2, 3 or more shorter sentences.
It often makes what I’m trying to express more easily understandable.
If we’d have such a style guide rule, would most sentences be less than 80 characters?
That could avoid most of the perceived downsides of not wrapping at 80 characters?
I am going to have to be the odd one out here and say that while I spend a lot of my time in VScode I drop down to the terminal for a lot of things, especially editing document files. It is difficult to know how bad it would be but I am more than a bit wary here.
I’ll be another odd one out and -1 this personally. I like how the 80 character limit means the documentation source is readable no matter what viewer you’re using. We’re already loose with this and I think that’s to our benefit, but I like that large blocks of text and readable as .txt files. I mainly use Vim, so editing documentation for me is just typing the text-as is, then using gqap to reflow it if necessary when I’m done. Needing to split this up by sentences would be more effort.
I see that I’m the minority opinion here, and it’s a relatively small change, but for me this is a step-down for readability and convenience.
In addition to points raised by @jhuber6 and @shafik , I am worried that without more specific guidelines and/or limit, we will end up with very wide lines in various files. That will lead to us requiring to enable line-wrap unconditionally.
I am also concerned that without a limit, we will end-up mixing styles. Some people will write very long lines. Others will wrap them at 80 chars (not to mention the existing docs that adhere to this style). I find consistency incredibly helpful.
This is why I like having explicit limits
+1
If the current guidelines are too limiting for folks, lets start by relaxing them rather than completely abolishing them.
Most modern editors have conditional word-wrapping by file type.
It’s not the length, it’s the idea. As I said above, line breaks are not semantically relevant in prose. I’d prefer to have a phrase word count soft limit, than a character count hard limit.
Now that two people suggested defining a different column limit, I feel compelled to provide illustrations for the reviewer experience. I consider it the most important, because the scarcity of reviewer time has been brought up time and again on those forums. Below is a change I want to propose to Clang’s internals manual.
Just two new words in the second sentence, and it’s immediately obvious.
First and foremost this RFC argues against reflowing that is currently required.
Separately, I’m surprised to hear from users of such advanced and flexible editor as vim that they have troubles enabling automatic word wrap to view files that don’t follow 80 column limit.
I didn’t say that, I said that having a fixed column limit makes the source read typographically even if viewed from cat or any other method. My complaint about formatting on a sentence break is that it requires me to format it as I’m typing it. Reflowing on the other hand is either done automatically as I type or is done in a single command at the end. You could obviously make tools to reformat like this automatically if it became an issue.
I’m not disagreeing that the reviewer experience is better here, but I think the reader / editor experience is better with fixed columns.
I apologize if that was too aggressive. I had vim users reaching out to me privately, which contributed here. Thank you for clarifying the use cases you had in mind.
Editor experience — sure, but reader experience? I expect that most of our users consume documentation in the rendered format, which offers navigation, styling, etc.
Do you still consider those concerns to outweigh benefits for reviewers that this RFC would bring?
FWIW, my personal preference would actually be to not use “one sentence per line” but rather “one paragraph per line”. This avoids any need for manual formatting and will still produce good diffs (in any environment that does world-level diffing, like GitHub).
Breaking at paragraphs > breaking at sentences >> breaking at specific column count.
