PSR-2: Opening braces

I feel that we're all sharing personal opinions of what we like and don't like about a coding standard that has now become a standard onto which PHP code is validated. When code doesn't comply with these rules warnings are generated and even if we can mentally ignore them they become a subject of conversation every time I roll a new PHP developer onto a Drupal project.

"No, Drupal has it's own coding standards. You should ignore those warnings"

"No, there isn't a technical reason why we don't implement opening brackets that way, brackets are brackets. We just prefer to keep them on the same line"

"Yes, Drupal complies with many of the PSR standards just not this one."

"No, we've talked about it before and I don't think there's a buy-in for making the change"

"Sure, here's an issue where you can go to complain"

...and they never do because that's too much work / investment. But I've had variants of that conversation many times with PHP devs.

That's a fair point @dawehner.

I understand that I'm entering this discussion at a point where it already has a great amount of history. And that between the 4 of us that have commented at least half don't like the aesthetics of the standard. mikeryan even questioned the original intent of this specific standard and how the standards came to be. That would be a thing I could research and report back to you.

But for now let's revisit the reason why we have standards.

"Remember that the main advantage of standards is that every piece of code looks and feels familiar, it's not about this or that being more readable."

- excerpt: http://symfony.com/doc/current/contributing/code/standards.html

Laravel is an interesting example to bring up because it was a project that maintained it's own coding standards for a long while. Eventually they shifted to PSR-2 coding style because they wanted to improve the developer experience by not forcing PHP developers a special way just for them. Now devs that work on PSR-2 PHP projects and Laravel projects can have a common expectation and understanding while reading code from either. Don't we want that?

Do we want developers to have to adapt their way of thinking and reading code so that they can start understanding Drupal code?
Are we comfortable with the uncanny valley we present when we show objects and methods with a different kind of opening brackets?
Do we want our code's quality to be judged by the number of warnings that are returned from a standard code sniffer?

@mikeryan brought up that

the inconsistent treatment of opening braces for classes and methods is the very worst part of PSR-2.

I don't understand what you mean. Being able to visually differentiate class and method declarations from control statements sounds like a pretty good idea to me. Furthermore you can modify the listing of method arguments and be sure you won't erase the opening bracket. So this makes sense (to me).

I understand that in this issue queue we're proposing changes to our coding standards, gathering consensus, and eventually moving forward with approved changes. I think what I am trying to understand the most from this particular thread is what our intent is. Should Drupal's coding standards be a thing that someone just knows because they've worked a lot on PHP projects? Or do we want them to learn Drupal with the knowledge that they'd have to unlearn them if they work on non-Drupal things?

At the same time, a lot of tools are gathering around the PSR-2 standard. Tools like PHP Code Sniffer, PHP CS Fixer, and Scrutinizer all support PSR-2 out of the box. You have to (and we have) put extra work to adapt these to abide by our rules. But what if they just worked?

What if we made it easier for junior developers to discover the tools and techniques it takes for them to gain confidence with our codebase?

What if discussions around our code was solely focused on it's merits and not it's code style?

When I think of all the things we could do to improve the Developer Experience for the next batch of new developers jumping onto Drupal for the first time, this is the kindest, most helpful form of mentorship we could provide. By forcing them to learn something they'd never use outside of Drupal, we're setting them up for frustration.

Now I'm confused.

I was told I needed to make a concrete proposal before the coding standards committee would take up my concerns. Are you saying that creating an issue in this queue is not the proper way to have a conversation about proposals like this?

Are you saying that I need to get people to agree to adopt all of PSR-2 before we can move forward with this smaller change?

Over the past two months I have been trying to raise attention to small steps we could be making today to adopt more of PSR-2. Every other place I've raised these concerns my comments have either been removed or ignored. That's a lot of time to be treated this way.

And now you're saying that in order to make progress I'm going to have to push back against the weight of a five month old issue that seems to have a lot of negativity in it and even some FUD.

Let's say I do that. Let's say I jump in there and make my case. Would it be a different conversation? Sounds like it'll be just me saying Standards are important / allowing PHP developers to ramp up on Drupal without the uncanny valley is important and then a majority of comments say no because they don't like it.

Well what about our audience for this change. What about all the people who wouldn't bother to jump onto a Drupal issue queue. Do they not get a say because they haven't invested years into Drupal like we have?

That's why I need some help understanding what our standards process is. I want to be a positive force for change. How can I do good things here?

@dawehner, you know me. I don't want to ignore you. I want to engage you in this conversation.

I have asked many questions here. I honestly want answers to them. Who should I talk to to get the answers? Where do I need to go. What process and procedure do I need to follow. I can make this a focus if the task requires it.

Then I can provide feedback on the process so that it can evolve like everything else. But it starts with conversation.

What is my next step here?

Certainly not something we would want to do in a minor release. Drupal 9 would be first opportunity to make this change. And even so we should expect the disruption that @pfrenssen has outlined.

We should recognize that this is more than a "cosmetic" issue. This is about the uncanny valley we present programmers who come to Drupal who have gained significant experience with PHP outside of our Drupal experience. To them, we present fundamentally flawed code as it violates the generally accepted code formatting standards that the rest of the PHP community has agreed upon.

What we're saying in this thread, is that we're ok with that. True, the code validating situation has improved greatly as a result of having tools like phpcs properly use rulesets that enforce Drupal's coding standards. But it is also true, that we want PHP developers adjust to our coding standards rather than adjusting our coding standards for developers. Explicitly, we're fine with this level of unfriendliness towards PHP developers.

My main concern in all of this has been that it was previously hard and at times impossible to get my favorite tools to use the Drupal rulesets. This issue was magnified for me when I had to support others who had a hard requirement that all code pass phpcs before committing. Now that problem has been alleviated as we have figured out how to get that working on our end. Yet the stigma remains. Drupal is both like modern PHP and it isn't. It's in an uncanny valley for the professional PHP developers I work with. Over time the devs I work with become more comfortable navigating through the unspoken boundaries between Drupal PHP and PHP, but initially there is the "explaining" period where I have to point out the Drupalisms.

Please note the previous conversation this thread has received. This issue was created because I was told I needed to make a concrete proposal in order to be considered. I was also advised not to create a "We should adhere to PSR-2" issue because it apparently was already discussed and the specific developers who comprise the coding standards group didn't want it, therefore proposing it again would be a waste of time. Therefore, I created this specific issue for consideration.

I chose this issue based on the feedback I received from the professional PHP developers I worked with. Of all the specific code standards violations this was the one that upset them the most.

Now, two years after I created this issue, after gaining a minuscule of momentum based on a few developers finding this issue for the first time, the feedback has changed, to paraphrase, "This doesn't go far enough".

I would appreciate some concrete direction on what my next steps should be, continue to push for specific concrete and atomic change? Or to start a new push for "Drupal should adopt PSR-2".

To your point of enforcing a new coding standard on Drupal 7

As discussed recently, introducing this code formatting standard change would be disruptive. Therefore we wouldn't want to introduce it until the next major release. Given our policy of only supporting Drupal(Current) and Drupal(Current - 1), this would mean that introducing the code formatting standard at that time would not mean that we would have to modify Drupal 7 code as Drupal 7 would fall out of support. However, it would mean a disruption for Drupal 8 around the time of Drupal 9's release. Something we would want to avoid.

This begs the question, is Drupal code formatting standards to stay the same forever? Or is it only 100% ensured to not be disruptive changes that are allowed?

The need to find a mutual purpose

If so, what are we doing here? What's the point of any of these discussions? Changing the code formatting standards, if allowed at all, for a project that is over 15 years old, is inherently disruptive and perhaps reckless given the fact that we're not talking about adding functionality or "fixing bugs" other than the code formatting warnings and advised corrections that command line tools and intelligent code editing tools flag as problems that the developer should fix.

I would hope that the purpose of this governing group is to improve the developer experience for new Drupal developers and experienced Drupal developers. To ensure that the code provided by the project meets the expectations of "good code" for those developers. What better way to do that than adopt a code formatting standard that is also used by the PHP professional community?

Imagine: one coding standard, one set of expectations, for PHP developers who work on standard PHP and/or Drupal. We can reduce the weirdness to implementation details and not distract newcomers with silly stuff like code formatting standards.

If we don't share a mutual purpose, then we need to make clear what our purpose is here. We need to make clear that the purpose of Drupal's code standards is to provide code that Drupal developers expect and explicitly doesn't make any effort to adhere to PHP coding standards outside of Drupal's island of code. And that we understand that if you learned PHP outside of Drupal that you'll need to put an extra effort into adopting Drupal's way of doing things to cross that uncanny valley.

My hope this isn't a knee jerk reaction

@pfrenssen, once you read the comments in this thread in their entirety, I hope you can see the same pattern I have. Talking about coding standards from a minority perspective in this thread is starting to seem impossible. At any time in this thread, all it takes is one individual to say, to paraphrase, "I don't like it", or "Too disruptive", or "That would be effectively pointless" without recognizing that any code formatting change is inherently subjective, disruptive, and effectively pointless. At the same time, I feel I'm representing a voiceless minority that don't bother to create Drupal accounts but would be more interested in working with Drupal's code if it didn't spam their automated processes and tools with errors if they get included into the project.

We need a better mode of communication here. We need to find mutual purpose. I'm sure we have mutual respect. I know everyone involved here is speaking from a perspective of trying to decide what's best for the project. I just don't think we agree on what that means.

Sure, we can continue to accrue these +1's and -1's.

It seems that what you're saying is that all we need to break the holding pattern on this issue is to have developers who may be impacted by this change (including all developers who may work with Drupal within their projects but don't have Drupal accounts) login and add a single +1 or -1 comment to this thread.

You've asked that the discussion remain focus on simply adding those votes and to the pros and cons of this change.

Pros:
- Follows the PSR-2 code formatting standard
- Makes code more consistent with expectations of PHP developers.
- Less friction with automated code validating tools

Cons:
- Wide impact of change
- Visual improvement is subjective
- Code improvement is negligible
- No Functionality improvement
- Disruptive to Drupal 8 code.