Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123008
Subject: Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
To: internals@lists.php.net
References: <792b2282-b7a3-40dd-899c-daab55353316@bastelstu.be>
 <69107662-eb03-4b75-8eed-59dd2eed6559@gmail.com>
 <66103C7A.3040906@adviesenzo.nl>
 <80ac7108-e016-4ae8-87ad-50afa0c2f257@bastelstu.be>
 <37f1b0c6-a7c8-41f3-bf2f-7dd466bb31c9@app.fastmail.com>
 <66106DDF.6050308@adviesenzo.nl>
 <2eb57476-1952-44f7-8408-762faa4f5971@bastelstu.be>
Message-ID: <661222EE.3050303@adviesenzo.nl>
Date: Sun, 7 Apr 2024 06:37:02 +0200
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:38.0) Gecko/20100101
 Thunderbird/38.7.0
Precedence: bulk
MIME-Version: 1.0
In-Reply-To: <2eb57476-1952-44f7-8408-762faa4f5971@bastelstu.be>
Content-Type: multipart/alternative;
 boundary="------------050008070003080005020206"
From: php-internals_nospam@adviesenzo.nl (Juliette Reinders Folmer)

This is a multi-part message in MIME format.
--------------050008070003080005020206
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit

On 6-4-2024 14:55, Tim Düsterhus wrote:
> Hi
>
> On 4/5/24 23:32, Juliette Reinders Folmer wrote:
>> I also took the liberty to ask accessibility expert Nicolas Steenhout
>> [1] for his opinion on this topic and he has given me permission to
>> quote his reply:
>>
>>   > From a human readability and an accessibility perspective, Camel 
>> Case
>> are best when words are concatenated like that.
>>   > The rule I’d use here is uppercase the first letter of a word. Then
>> lowercase the others. Unless you are writing an acronym.
>>   > So in your example, it should be `PerformHTTPRequest()`
>>   > The underscore becomes a problem because if for some reason we’re
>> writing code as an example and it gets underline for any reason, the
>> underline gets lost
>>
>
> Thank you. I must admit I find it a little hard to interpret the 
> answer without also seeing the corresponding question, because the way 
> the question was phrased might've influenced the answer.
>
> While I personally disagree with the acronym casing, it is not too bad 
> in the example identifier used ("Perform HTTP Request"). However the 
> naming policy will not just need to make the average case look great, 
> but also make the worst case look acceptable. If it cannot do so and 
> needs exceptions, then it failed to be a useful policy.
>
> Hoping it isn't too much of a request, would you mind asking Nicolas 
> whether the answer changes, when facing the following extreme examples 
> consisting of consecutive acronyms.
>
> I'm intentionally writing them in their natural casing with spaces to 
> hopefully not influence the response:
>
> 1.
>
> PCG Oneseq 128 XSL RR 64
>
> which for reference is "Permuted Congruential Generator One Sequence 
> 128-Bit state XorShift Low Bits Random Rotation with 64-Bit Output", 
> with the abbreviations / acronyms matching the naming in the reference 
> implementation / corresponding paper.
>
> 2.
>
> PDO ODBC
>
> which is "PHP Data Object Open Database Connectivity", but no one 
> writes those acronyms out in full.
>
> 3.
>
> XML HTTP Request
>
> which is "eXtensible Markup Language HyperText Transfer Protocol 
> Request". I'd argue that the name is not really descriptive in the 
> first place, but it's another existing real-world example.
>
> 4.
>
> UUID v4
>
> Taken from Ben Ramsey’s UUID library: 
> https://github.com/ramsey/uuid/tree/4.x/src/Rfc4122
>
> 5.
>
> S3 Client
>
> as in "Amazon Simple Storage Service Client". Taken from Flysystem: 
> https://github.com/thephpleague/flysystem/blob/3.x/src/AwsS3V3/S3ClientStub.php
>
> Best regards
> Tim Düsterhus
>

Hi Tim,

I forwarded your questions from above verbatim to Nicolas and this was 
his response (also quoted verbatim):

 > So, this one is interesting.
 > Sure, if you look at these extremes, stringing them back to back all 
in a uppercase, they are not particularly user-friendly to read.
 > Then again, none of these solutions are super user-friendly. We are 
dealing with making the best of things.
 > I have to say, it always gets my goat a little bit when people raise 
“the extremes” in the context of accessibility. Somehow it always ends 
up feeling like, to me at least, like a copout.
 > Like, sure if you have someone who is blind, deaf, and paralyzed from 
a stroke, making something accessible to them is going to be extremely 
difficult. It doesn’t mean you shouldn’t make things accessible to 
people who are blind, to people who are deaf, and to people who are 
paralyzed from a stroke.
 > This is a little bit like that. The solution I proposed earlier may 
not work for everybody. But it will work for a majority.

Smile,
Juliette

--------------050008070003080005020206
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 8bit

<html>
  <head>
    <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    <div class="moz-cite-prefix">On 6-4-2024 14:55, Tim Düsterhus wrote:<br>
    </div>
    <blockquote
      cite="mid:2eb57476-1952-44f7-8408-762faa4f5971@bastelstu.be"
      type="cite">Hi
      <br>
      <br>
      On 4/5/24 23:32, Juliette Reinders Folmer wrote:
      <br>
      <blockquote type="cite">I also took the liberty to ask
        accessibility expert Nicolas Steenhout
        <br>
        [1] for his opinion on this topic and he has given me permission
        to
        <br>
        quote his reply:
        <br>
        <br>
          &gt; From a human readability and an accessibility
        perspective, Camel Case
        <br>
        are best when words are concatenated like that.
        <br>
          &gt; The rule I’d use here is uppercase the first letter of a
        word. Then
        <br>
        lowercase the others. Unless you are writing an acronym.
        <br>
          &gt; So in your example, it should be `PerformHTTPRequest()`
        <br>
          &gt; The underscore becomes a problem because if for some
        reason we’re
        <br>
        writing code as an example and it gets underline for any reason,
        the
        <br>
        underline gets lost
        <br>
        <br>
      </blockquote>
      <br>
      Thank you. I must admit I find it a little hard to interpret the
      answer without also seeing the corresponding question, because the
      way the question was phrased might've influenced the answer.
      <br>
      <br>
      While I personally disagree with the acronym casing, it is not too
      bad in the example identifier used ("Perform HTTP Request").
      However the naming policy will not just need to make the average
      case look great, but also make the worst case look acceptable. If
      it cannot do so and needs exceptions, then it failed to be a
      useful policy.
      <br>
      <br>
      Hoping it isn't too much of a request, would you mind asking
      Nicolas whether the answer changes, when facing the following
      extreme examples consisting of consecutive acronyms.
      <br>
      <br>
      I'm intentionally writing them in their natural casing with spaces
      to hopefully not influence the response:
      <br>
      <br>
      1.
      <br>
      <br>
      PCG Oneseq 128 XSL RR 64
      <br>
      <br>
      which for reference is "Permuted Congruential Generator One
      Sequence 128-Bit state XorShift Low Bits Random Rotation with
      64-Bit Output", with the abbreviations / acronyms matching the
      naming in the reference implementation / corresponding paper.
      <br>
      <br>
      2.
      <br>
      <br>
      PDO ODBC
      <br>
      <br>
      which is "PHP Data Object Open Database Connectivity", but no one
      writes those acronyms out in full.
      <br>
      <br>
      3.
      <br>
      <br>
      XML HTTP Request
      <br>
      <br>
      which is "eXtensible Markup Language HyperText Transfer Protocol
      Request". I'd argue that the name is not really descriptive in the
      first place, but it's another existing real-world example.
      <br>
      <br>
      4.
      <br>
      <br>
      UUID v4
      <br>
      <br>
      Taken from Ben Ramsey’s UUID library:
      <a class="moz-txt-link-freetext" href="https://github.com/ramsey/uuid/tree/4.x/src/Rfc4122">https://github.com/ramsey/uuid/tree/4.x/src/Rfc4122</a>
      <br>
      <br>
      5.
      <br>
      <br>
      S3 Client
      <br>
      <br>
      as in "Amazon Simple Storage Service Client". Taken from
      Flysystem:
<a class="moz-txt-link-freetext" href="https://github.com/thephpleague/flysystem/blob/3.x/src/AwsS3V3/S3ClientStub.php">https://github.com/thephpleague/flysystem/blob/3.x/src/AwsS3V3/S3ClientStub.php</a><br>
      <br>
      Best regards
      <br>
      Tim Düsterhus
      <br>
      <br>
    </blockquote>
    <br>
    Hi Tim,<br>
    <br>
    I forwarded your questions from above verbatim to Nicolas and this
    was his response (also quoted verbatim):<br>
    <br>
    &gt; So, this one is interesting.<br>
    &gt; Sure, if you look at these extremes, stringing them back to
    back all in a uppercase, they are not particularly user-friendly to
    read.<br>
    &gt; Then again, none of these solutions are super user-friendly. We
    are dealing with making the best of things.<br>
    &gt; I have to say, it always gets my goat a little bit when people
    raise “the extremes” in the context of accessibility. Somehow it
    always ends up feeling like, to me at least, like a copout.<br>
    &gt; Like, sure if you have someone who is blind, deaf, and
    paralyzed from a stroke, making something accessible to them is
    going to be extremely difficult. It doesn’t mean you shouldn’t make
    things accessible to people who are blind, to people who are deaf,
    and to people who are paralyzed from a stroke.<br>
    &gt; This is a little bit like that. The solution I proposed earlier
    may not work for everybody. But it will work for a majority.<br>
    <br>
    Smile,<br>
    Juliette<span style="color: rgb(29, 28, 29); font-family:
      Slack-Lato, Slack-Fractions, appleLogo, sans-serif; font-size:
      15px; font-style: normal; font-variant-ligatures:
      common-ligatures; font-variant-caps: normal; font-weight: 400;
      letter-spacing: normal; orphans: 2; text-align: left; text-indent:
      0px; text-transform: none; widows: 2; word-spacing: 0px;
      -webkit-text-stroke-width: 0px; white-space: normal;
      background-color: rgb(248, 248, 248); text-decoration-thickness:
      initial; text-decoration-style: initial; text-decoration-color:
      initial; display: inline !important; float: none;"><br>
    </span>
  </body>
</html>

--------------050008070003080005020206--