Allow lines to be longer than 80 chars if they're unbreakable in comments

[JulienPalard]

A probably "a bit too general" title, to open the discussion, but here are the facts:

Sometimes, in docstring, we're dropping some URL to some specs / external doc / references, like:

 /**
  * Does something cool, blah blah, not so long line.
  *
  * We're using Wilson scoring because blah blah, see:
  * http://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval
  */

As this block can be used to generate documentation (to PDF, HTML, ...) and also to be cool with editors that can transform links to buttons (clickable), there is no valid way to split those URLs.

So the dillema pops: What do we do here ?

So here are some proposals for rules like Generic.Files.LineLength.TooLong:

• Rules may have an option to not complain if the too long line is an URL.
• Rules may have an option to not complain about "probably unbreakable too long lines" typically those not containing any spaces but the leading ones (like "space * space" in a multiline docstring comment block).
• What about discerning unbreakable "too long lines" from strings and for comments ? Allowing one but not the other as options ?

I'm personally not into allowing variables containing too long URLs, but why not ? But I'm a bit more into allowing comments block to contain long URLs and PHPCS not complaining about it.

See also this issue in Python's PEP8 checker: PyCQA/pycodestyle#242 for a similar discussions.

[gsherwood]

I think it would be best to start with comments. Figuring out if code is unbreakable is pretty tough because even the longest URL string could be broken up with concatenation.

So taking comments only, this might work:

For each line where $lineLength > $maxLineLength, the process might be:

1. determine the indent of the comment (call it $indent)
2. check the length from the last space to the end of the line (call it $endLength)
3. if $endLength + $indent > $maxLineLength, ignore the line as breaking it up would still cause a long line error

Example:

1: <?php
2: if (isset($chars[$foo]) === true) {
3:     // We got the char list from the
4:     // really great site http://www.example.com/char-lists/all/2015/type-a/full-char-list.php#special
5: }

Line 4 has indent of 7 chars. The length of the line is 101 characters and we set the max length to 80 chars. The length from the last space to the end of the line is 76 chars (the length of the URL).

76 chars + 7 char indent is greater than 80, so the line cannot be split and should be ignored.

If the max line length was 100 chars, PHPCS would still complain because 83 chars would fit within that 100 char line limit.

[JulienPalard]

It good for me to constraint this enhancement to only comments. Still, breaking long string using useless concatenations is not better in my eyes (as in PHP there's no implicit/compile time concatenations ("foo" "bar") like in C or Python). It would also break the "Unnecessary string concatenation" that exist in PHPCS: https://github.com/squizlabs/PHP_CodeSniffer/blob/bd21c5e97d77e3fb7b78fa9aaeaab19e023eb708/CodeSniffer/Standards/Generic/Docs/Strings/UnnecessaryStringConcatStandard.xml

[gsherwood]

It would also break the "Unnecessary string concatenation" that exist in PHPCS:

It doesn't. Splitting a string assignment to make the line more readable is perfectly acceptable to the sniff:

<?php
$myString  = 'This is a very long string ';
$myString .= 'that has been broken over multiple lines ';
$myString .= 'so it meets the line length limit';

[JulienPalard]

Wow, I'm opening #771 about it right now,

Let's focus on the comments blocks in this issue.

[polybuildr]

+1. Fixing this would be very helpful. There are certain comments in the MediaWiki codesniffer standard that refer to documentation pages of the coding standard. But since the line was too long, they end up being rewritten (wikimedia/mediawiki-tools-codesniffer@858ab2c) like this

// Per https://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP
// section on alternative syntax.

instead of

// Per https://www.mediawiki.org/wiki/Manual:Coding_conventions/PHP#Alternative_syntax_for_control_structures

in order to pass PHPCS.

[PortNumber53]

I also found the need for this while adding Swagger annotations to my API. If I wrap long descriptions over many lines, zircote/swagger-php keeps the line endings and Swagger-UI formatting breaks, or I have warnings on phpcs

[HillLiu]

👍 +1.

[gsherwood]

I've given this a shot using the rules I stated above in my comment. Seems to work ok. I've got a couple of tests in there, but if anyone has time to actually test this before release, please do and comment here with any problems.

[jrfnl]

@djouuuuh Why are you scanning .md files with PHPCS ?

[fabswt]

It's not clear to me. In the end, is there a rule to ignore line length if the line is ending with a URL?

e.g.

/**
 * …
 *
 * The API is documented here:
 * - Overview: https://github.com/googleapis/google-cloud-php-translate
 * - Reference: https://googleapis.github.io/google-cloud-php/#/docs/google-cloud/v0.116.0/translate/v3/translationserviceclient
 * - These docs are NOT kept up to date https://cloud.google.com/translate/docs/
 */