Proposal: Change docblock line wrapping to 120 characters

[johnbillion]

I am proposing that the "Line wrapping" guideline for docblocks in PHP and JavaScript files is changed so it is fixed at 120 characters. The current guideline is:

DocBlock text should wrap to the next line after 80 characters of text. If the DocBlock itself is indented on the left 20 character positions, the wrap could occur at position 100, but should not extend beyond a total of 120 characters wide.

Issue Description

80 characters is very narrow. A large proportion of docblocks in WordPress core don't adhere to this, especially when it comes to @param tags with detailed documentation and array arguments which use the extended @type syntax. If the line length limit is assumed to be 80 characters then it's possible for over half the length to be taken up before the description starts.

URL of the Page with the Issue

1. https://developer.wordpress.org/coding-standards/inline-documentation-standards/javascript/#line-wrapping
2. https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#formatting-guidelines ("Line wrapping" section)

Why is this a problem?

Docblocks in PHP and JavaScript files have line lengths of varying width. There is little consistency.

Suggested Fix

Let's set the recommended line length limit to 120 characters in all cases.

[jrfnl]

@johnbillion Changes to the coding standards need to be proposed on Make.

[johnbillion]

I'll get something written up.

In the meantime, I'm struggling to find anywhere that documents the process for proposing a change to the docs standards. Is it documented somewhere that I'm missing?

[dingo-d]

I don't think there is an official process documented, but when we did the WPCS 3.0.0 changes that included tons of changes for the docs, we were doing them based on the proposal Juliette wrote. The same happened a year earlier when Gary Pendergast wrote his proposal about CS changes.

The proposal had a discussion, and based on this discussion we made changes, both in the handbook and in the WPCS itself.

[jrfnl]

Indeed, but that was after we were told - in no uncertain terms - that any changes had to go via a proposal on Make. There is also no formal way of how the decision whether a proposal is accepted or not is to be made.... ... which became very clear with the (abolish) Yoda conditions proposal which had overwhelming support in the comments and on the underlying GH issues, but was still blocked.

At some point in the distant past, there was an idea to have an RFC process, but that idea was killed before it ever got off the ground. 🤷‍♀