naming PSR

[Lukas Kahwe Smith]

Aloha,

So the topic of naming things has become even more discussed as in the previous years in part due to recent protests in the world.

I think most of us are familiar with the saying "There are only two hard things in Computer Science: cache invalidation and naming things."

Many of us are also familiar with the concept of design patterns and the value there is when discussing approaches to having commonly understood and agreed upon words for these design patterns.

Let me also add this link here to explain that language in fact also shapes how we think

https://www.ted.com/talks/lera_boroditsky_how_language_shapes_the_way_we_think

So I hope this video helps to understand that technical jargon isn't just technical jargon. But I still often hear the argument that changing words isn't really needed since it is not a big deal and there are bigger issues. So I invite you to read this twitter thread

https://twitter.com/btanderson72/status/1279507428128718848?s=20

Now I do agree that there are bigger issues but those go beyond the scope of this group. I do however think that offering inclusive terminology is within the scope of this project, especially since it is very useful for us all to agree on the same terminology.

More importantly we have come to accept a lot of very inaccurate terms for technology that needlessly complicate things for new comers.

For example if you don't know the term "whitelist" or "blacklist" you don't know what they mean. While black might refer to the absence of light, white might also refer to the absence of color. As such "allowlist" or "denylist" are simply more expressive ways to describe things. Similar master/slave isn't as accurate as primary/replica to describe the relationship (though of course depending on the specific context there might be even better terms to use). So all I want to say is that if you don't agree that technical jargon can be offensive, I hope you still agree that if we re-use terms from non technical contexts, we should make sure that the analogy is as self-descriptive as possible to prevent misunderstandings with new comers or even just people we interact with as part of our work (product owners, investors etc).

As part of the IETF there is a a document that addresses the above noted terms:

https://tools.ietf.org/id/draft-knodel-terminology-00.html

Chromium project also has some more guidelines that cover also terms we might commonly find in documentation or comments

https://chromium.googlesource.com/chromium/src/+/master/styleguide/inclusive_code.md#racially-neutral

Now there has also been discussion about the git master branch (and yes it is derived from master/slave https://github.com/bitkeeper-scm/bitkeeper/blob/master/doc/HOWTO.ask?WT.mc_id=-blog-scottha#L231-L232, though I don't think it matters much if it does or not, see above twitter thread).

Here to it might make sense to actually recommend projects to not use master as the default branch for “latest”

https://mikevanriel.com/2020/07/07/master-has-always-been-a-poor-branch-name/

Python has been a language and community that has already done steps in this direction a long time ago

https://bugs.python.org/issue34605

https://github.com/django/django/pull/2692

Drupal as well https://www.drupal.org/node/2275877

Other PHP projects like PHPUnit and Doctrine, Symfony more recently

I have started a discussion about this on slack a while ago already but would like to bring this to the list. Based on the discussion on slack there were opinions that ranged from:

* do nothing

* agree to not use those terms in PSRs

* create a bylaw to clarify that those terms will not be used in PSRs

* create a PSR as a recommendation for a unified (and inclusive) language used within Frameworks when it comes to naming things. (and then a bylaw to also follow that PSR)

I believe the latter should be done. This is also a huge benefit (not only about the currently hot debates) for PHP developers as they know how things are named across libraries. We had a similar topic about PSR-14 "Events" (what do people mean when they say "Events"). So the scope can be wider than “just” inclusive language.

I also believe this topic is very much within the scope of FIG. We have PSRs for PHPDoc naming. I once proposed a PSR for security disclosure which got abandoned not due to a discussion about the scope but simply because work was never pushed forward sufficiently.

We may or may not include other terms than those I mentioned above. If the list needs to be expanded later we can always publish another PSR, just like for PHPDoc etc.

From what I have seen on the web, this topic tends to get incredibly heated. As such I would ask everyone to spend a few extra minutes formulating their replies to ensure maximum clarity. Also I would ask readers to spend some additional time digesting responses and potentially throttle your responses. I really hope we can have a productive discussion here and not a shouting match.

There might be people reading this and they think it's not as important, but still would be up for adopting it, if a Working Group would work on it. Feedback as such would be helpful as well from this list

--

regards,

Lukas

[Woody Gilk]

I like the idea of a PSR for unified, inclusive language. Though I do wonder if a PSR is the right type of document for such a thing, given that it isn't going to produce any code contract.

Perhaps a living document as part of FIG's website would be a better place?

--
Woody Gilk
https://www.shadowhand.com

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAEFKHaF_TFgnFhJweRQRBFZ9gNk%3D5rE%3DmMsGz%3DMAE54L0wBSZg%40mail.gmail.com.

[Massimiliano Arione]

I can just say that I totally agree with the topic.

[Christopher Feamster]

Lukas,

I have been lurking in this group forever and a day and this is the first time I've been compelled to reply to anyone!

I must say how much I agree with every single point in this message. I am a small business owner, a PHP developer, and a "nerd" for almost all of my life. I am also black. I grew up around this jargon and I have *always* felt a "twinge" at the back of the neck when discussing these terms. It's bothered me. I have had many a fraught moment when deciding names and naming policies in my own codebases. Each time I concluded "This is everywhere. No one cares about this but me, and no one means anything by it, so I should let it go". *Clearly* I was not the only one, and others have not let it go... 

Furthermore, that collective "twinge" (and the reasons behind it) are *more* than enough of a reason to bring it up, and *now* is a better time than any other to figure it out, for everyone. 

I applaud you.

I thank you. 

Please, keep talking about the "twinges" :)

-Thank You

---

Chris R. Feamster Chief Executive Officer	Performance, Reliability, Style
Mobile: 215-840-7617 Email: cfea...@nxs.systems IM: feamsr00 (Skype) http://www.linkedin.com/in/cfeamster	630 North 16th Street Philadelphia, PA 19130 USA www.NexusSystemsInc.com

--

[Enrico Zimuel]

Lukas, thanks for writing this and for sharing  such interesting references.

I really enjoyed the TED talk https://www.ted.com/talks/lera_boroditsky_how_language_shapes_the_way_we_think and I think that everyone should watch it, very educational.

I think naming is very important, especially for a group of people like us with representatives around the world. We use a common language (English) for proposing common standards using technical terminology.

Sometimes we use words that have different meanings/reactions for many people, like the one that you mentioned master/slave, whitelist/blacklist, etc.

I think we should do something as a group and I'm in favor of creating a PSR for a unified, inclusive language.

Woody, I think it's fine having a PSR that doesn't produce any code contract (see PSR-1 and PSR-4). I would love to see in the future a PHP library with the statement "compliant with PSR-x for using an inclusive language". I think this will be awesome!

Regards,

Enrico Zimuel

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6KPzdSfUpMsxkd2UYYOkfvVoeOdZ%3D4B4PQFruj%3DYCEvEQ%40mail.gmail.com.

[Lukas Kahwe Smith]

Aloha,

First up Chris thank you for your input specifically.

Happy to see so many voices of support as well.

In general: Who would be motivated to work with me on shaping a proposal? Please contact me directly via slack, email, twitter (@lsmith) ..

Note: For now I would put the scope on inclusive language only. However I think in parallel work could also be done on maybe looking at other sources for issues in naming like the Events example I mention.

regards,

Lukas

--

regards,

Lukas

[Lukas Kahwe Smith]

Sorry for the long silence. I am still very much committed the the topic.

From the feedback I got here, on FIG slack and other places there were quite a few voices that feel like a PSR isn’t the right format. I therefore decided to approach the topic more as “what would I as a developer/documentor/etc need” to more easily be able to use inclusive language?

Jenny Wong shared with me documentation they created at the company she works at:

https://engineering.hmn.md/standards/naming-things/

This document tries to essentially cover the general considerations, some concrete examples but then links to additional resources.

Most notably it links to the following guide by google which seems to be the most complete and well structured document I found on the topic:

https://developers.google.com/style

My only criticism is that it might be a bit overwhelming. So I think it is specifically something people that act as editors for documentation should be fully aware of but as a general resource I fear it could lead to people giving up as it feels too big an effort to make any difference.

So I think I like the approach of giving an overview, I also like giving detailed examples but I would then add a bigger section which can be read in 5-10mins with less details that should be enough to make a material impact and then linking other more detailed resources at the bottom.

Now this approach indeed might not lend itself to a PSR which I guess is the type of document that is more definitive and where compliance can be determined in a more binary fashion.

I do however want a document that actively encourages PHP projects to adopt it. 

I also do want to also offer some sort of method to more easily validate (or at list get a list of things to review in detail) both code and documentation (https://github.com/OskarStark/doctor-rst/blob/master/src/Rule/BeKindToNewcomers.php). Maybe also discussions on their chat (https://github.com/keoghpe/alex-slack) and in pull requests.

Especially for chat/PRs I realize that people will likely tend towards becoming defensive and others might get annoyed by the disruption if the comments are done inside the normal discussion. As such the best approach might be a throttled (opt-in?) feedback via a separate channel (DM, email). See also

https://github.com/keoghpe/alex-slack/pull/2

regards,

Lukas

--

regards,

Lukas

[Alessandro Lai]

Thanks Lukas for the continued effort on this topic. You're basically stumbling on a recurring problem that we have here at PHP-FIG: we don't have a way to stipulate a "living document", something that is similar to a PSR but can evolve.

IMHO this could actually work if we write down a new bylaw that handles this case, and it would solve similar issues like the coding standard (see PSR-12) where the PSR can't keep up with how fast the language is evolving.

I'll give this some more thought and try to find a way to draft a bylaw that encapsulates a basic solution to this.

[Lukas Kahwe Smith]

On Tue, Aug 11, 2020 at 6:02 PM Alessandro Lai <alessand...@gmail.com> wrote:

Thanks Lukas for the continued effort on this topic. You're basically stumbling on a recurring problem that we have here at PHP-FIG: we don't have a way to stipulate a "living document", something that is similar to a PSR but can evolve.

IMHO this could actually work if we write down a new bylaw that handles this case, and it would solve similar issues like the coding standard (see PSR-12) where the PSR can't keep up with how fast the language is evolving.

I'll give this some more thought and try to find a way to draft a bylaw that encapsulates a basic solution to this.

thx!

in the meantime, here is a first draft of a document about inclusive language

https://docs.google.com/document/d/1-5iNw4xcfWLquVoV22QceYHFKdKode0VEhmQaC3fbcQ/edit#

I have enabled comments/suggestions.

It can become whatever .. a PSR, a by-law or something else. Once we have figured this out we can convert it to a PR.

[Lukas Kahwe Smith]

some more work went into tweaking the language and structure. I have another review scheduled with a content expert at Liip. 

but I would also like to get an indication how to shape this further to fit FIG. 

I could envision moving the list of examples to a separate document that is neither a PSR or by-law but that is updated once per year (or more often), that is referenced from an inclusive language PSR similar to the other resources. 

wdyt?

regards

Lukas

--

regards,

Lukas