Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:122988
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>
Message-ID: <66106DDF.6050308@adviesenzo.nl>
Date: Fri, 5 Apr 2024 23:32:15 +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: <37f1b0c6-a7c8-41f3-bf2f-7dd466bb31c9@app.fastmail.com>
Content-Type: multipart/alternative;
 boundary="------------090207070606070305020209"
From: php-internals_nospam@adviesenzo.nl (Juliette Reinders Folmer)

This is a multi-part message in MIME format.
--------------090207070606070305020209
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit

On 5-4-2024 22:55, Larry Garfield wrote:
> On Fri, Apr 5, 2024, at 7:15 PM, Tim Düsterhus wrote:
>> Hi
>>
>> On 4/5/24 20:01, Juliette Reinders Folmer wrote:
>>> In the "It decreases readability" section you make a sweeping statement
>>> about accessibility, but don't back that up with research. Please back
>>> your statement up as based on my understanding, the opposite is true.
>> For context: This paragraph was added by Larry. It's my name on the RFC
>> of course and I approved of the addition he made. Nevertheless Larry
>> might've additional resources to add here.
>>
>>> Case in point: if written in all caps, screenreaders will spell the
>>> characters out - think HTML -. If written in Mixed case, screenreaders
>>> will try to pronounce the word, making acronyms and other abbreviations
>>> very hard to understand for anyone using a screenreader.
>>>
>>> This is something which has repeatedly been pointed out, for instance at
>>> conferences regarding conference acronym hashtags, like #DPC.
>>>
>>> So, I'd be very interested to see your statement backed up by actual
>>> research and invite you to look into this a little deeper.
>> Your remark looks at the accessibility from the PoV of a developer with
>> impaired eyesight that is dependent on assistive technology. However
>> accessibility also affects developers with regular vision. The concerns
>> of these two groups might conflict.
>>
>> W3C's accessibility guidelines point out that:
>>
>>   > Text in all capital letters is more difficult to read for most
>> people, with and without disabilities.
>>
>> (https://w3c.github.io/low-vision-a11y-tf/requirements.html#capitalization)
>>
>> Harvards's Accessibility Guidelines agree:
>>
>>   > Avoid using all caps. Readability is reduced with all caps because
>> all words have a uniform rectangular shape, meaning readers can't
>> identify words by their shape.
>>
>> (https://accessibility.huit.harvard.edu/design-readability)
>>
>> Of course program identifiers are not regular text and indeed more
>> similar to hashtags, in that they do not permit the inclusion of
>> whitespace to separate words. Underscores would work, but that would
>> just add to the inconsistency.
>>
>> For Hashtags I found several resources pointing out to capitalize each
>> word separately. For acronyms most resources pointed out that they
>> should be avoided entirely (e.g.
>> https://studentlife.mit.edu/das/accessibility/digital-accessibility/socialmedia,
>> https://www.nyu.edu/life/information-technology/web-and-digital-publishing/digital-publishing/accessibility/how-to-guides/social-media.html#acronyms)
>> and that recommendation is already part of the existing guidelines.
>>
>> I've tested with my Android phone with the 'performHttpRequest' example
>> and both variants where read out equally terrible as 'per-form age tee
>> tee pre-quest' (i.e. merging the p with the request). And your example
>> of HTML was read out as 'age tee em el' (or rather the German
>> pronounciation of the letters) for both HTML and Html. The lack of
>> vowels might've helped with the result, though.
>>
>> The case of the boundary between two consecutive acronyms being unclear
>> should affect developers with regular vision and impaired vision alike
>> (i.e. PDOODBC and XSLRR).
>>
>>   From my personal experience as a human with regular vision (not even
>> glasses), the variant of treating acronyms as regular words is much
>> easier to parse.
>>
>> Best regards
>> Tim Düsterhus
> Thanks Tim.  Those are the same resources I was going to cite. :-)  I'll also add
>
> >From the APA: https://apastyle.apa.org/style-grammar-guidelines/paper-format/accessibility/typography
>
> "It is true that presenting text in all caps will slow down all readers, especially those with certain types of visual and/or cognitive impairments."
>
> (They then go on to recommend using proper casing in the source and CSS styles to capitalize things, so that screen readers ignore it, which seems dumb to me given the other resources cited above.)
>
> And from the a11y Project: https://www.a11yproject.com/posts/how-to-accessible-heading-structure/#all-caps
>
> "Text in all capitals is harder to read. The shape of a word disappears, every word becomes a rectangle. Research shows that all caps text is especially difficult for readers with dyslexia. Make life easy for your readers, don't capitalize all the words."
>
> So the professional consensus among accessibility and publishing organizations is absolutely that ALLCAPS is bad for readability and accessibility.
>
> I've added some of the links above to the RFC for citation.
>
> --Larry Garfield
>

Larry, Tim,

Thank you both for your responses. I think it would be a good idea to 
include these sources in the RFC.

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

Hope this helps to inform the RFC further.

Smile,
Juliette


1: https://www.linkedin.com/in/nicolassteenhout/



--------------090207070606070305020209
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 5-4-2024 22:55, Larry Garfield
      wrote:<br>
    </div>
    <blockquote
      cite="mid:37f1b0c6-a7c8-41f3-bf2f-7dd466bb31c9@app.fastmail.com"
      type="cite">
      <pre wrap="">On Fri, Apr 5, 2024, at 7:15 PM, Tim Düsterhus wrote:
</pre>
      <blockquote type="cite">
        <pre wrap="">Hi

On 4/5/24 20:01, Juliette Reinders Folmer wrote:
</pre>
        <blockquote type="cite">
          <pre wrap="">In the "It decreases readability" section you make a sweeping statement
about accessibility, but don't back that up with research. Please back
your statement up as based on my understanding, the opposite is true.
</pre>
        </blockquote>
        <pre wrap="">
For context: This paragraph was added by Larry. It's my name on the RFC 
of course and I approved of the addition he made. Nevertheless Larry 
might've additional resources to add here.

</pre>
        <blockquote type="cite">
          <pre wrap="">Case in point: if written in all caps, screenreaders will spell the
characters out - think HTML -. If written in Mixed case, screenreaders
will try to pronounce the word, making acronyms and other abbreviations
very hard to understand for anyone using a screenreader.

This is something which has repeatedly been pointed out, for instance at
conferences regarding conference acronym hashtags, like #DPC.

So, I'd be very interested to see your statement backed up by actual
research and invite you to look into this a little deeper.
</pre>
        </blockquote>
        <pre wrap="">
Your remark looks at the accessibility from the PoV of a developer with 
impaired eyesight that is dependent on assistive technology. However 
accessibility also affects developers with regular vision. The concerns 
of these two groups might conflict.

W3C's accessibility guidelines point out that:

 &gt; Text in all capital letters is more difficult to read for most 
people, with and without disabilities.

(<a class="moz-txt-link-freetext" href="https://w3c.github.io/low-vision-a11y-tf/requirements.html#capitalization">https://w3c.github.io/low-vision-a11y-tf/requirements.html#capitalization</a>)

Harvards's Accessibility Guidelines agree:

 &gt; Avoid using all caps. Readability is reduced with all caps because 
all words have a uniform rectangular shape, meaning readers can't 
identify words by their shape.

(<a class="moz-txt-link-freetext" href="https://accessibility.huit.harvard.edu/design-readability">https://accessibility.huit.harvard.edu/design-readability</a>)

Of course program identifiers are not regular text and indeed more 
similar to hashtags, in that they do not permit the inclusion of 
whitespace to separate words. Underscores would work, but that would 
just add to the inconsistency.

For Hashtags I found several resources pointing out to capitalize each 
word separately. For acronyms most resources pointed out that they 
should be avoided entirely (e.g. 
<a class="moz-txt-link-freetext" href="https://studentlife.mit.edu/das/accessibility/digital-accessibility/socialmedia">https://studentlife.mit.edu/das/accessibility/digital-accessibility/socialmedia</a>, 
<a class="moz-txt-link-freetext" href="https://www.nyu.edu/life/information-technology/web-and-digital-publishing/digital-publishing/accessibility/how-to-guides/social-media.html#acronyms">https://www.nyu.edu/life/information-technology/web-and-digital-publishing/digital-publishing/accessibility/how-to-guides/social-media.html#acronyms</a>) 
and that recommendation is already part of the existing guidelines.

I've tested with my Android phone with the 'performHttpRequest' example 
and both variants where read out equally terrible as 'per-form age tee 
tee pre-quest' (i.e. merging the p with the request). And your example 
of HTML was read out as 'age tee em el' (or rather the German 
pronounciation of the letters) for both HTML and Html. The lack of 
vowels might've helped with the result, though.

The case of the boundary between two consecutive acronyms being unclear 
should affect developers with regular vision and impaired vision alike 
(i.e. PDOODBC and XSLRR).

 From my personal experience as a human with regular vision (not even 
glasses), the variant of treating acronyms as regular words is much 
easier to parse.

Best regards
Tim Düsterhus
</pre>
      </blockquote>
      <pre wrap="">
Thanks Tim.  Those are the same resources I was going to cite. :-)  I'll also add

&gt;From the APA: <a class="moz-txt-link-freetext" href="https://apastyle.apa.org/style-grammar-guidelines/paper-format/accessibility/typography">https://apastyle.apa.org/style-grammar-guidelines/paper-format/accessibility/typography</a>

"It is true that presenting text in all caps will slow down all readers, especially those with certain types of visual and/or cognitive impairments."

(They then go on to recommend using proper casing in the source and CSS styles to capitalize things, so that screen readers ignore it, which seems dumb to me given the other resources cited above.)

And from the a11y Project: <a class="moz-txt-link-freetext" href="https://www.a11yproject.com/posts/how-to-accessible-heading-structure/#all-caps">https://www.a11yproject.com/posts/how-to-accessible-heading-structure/#all-caps</a>

"Text in all capitals is harder to read. The shape of a word disappears, every word becomes a rectangle. Research shows that all caps text is especially difficult for readers with dyslexia. Make life easy for your readers, don't capitalize all the words."

So the professional consensus among accessibility and publishing organizations is absolutely that ALLCAPS is bad for readability and accessibility.

I've added some of the links above to the RFC for citation.

--Larry Garfield

</pre>
    </blockquote>
    <br>
    Larry, Tim,<br>
    <br>
    Thank you both for your responses. I think it would be a good idea
    to include these sources in the RFC.<br>
    <br>
    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:<br>
    <br>
    &gt; From a human readability and an accessibility perspective,
    Camel Case 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 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 writing code as an example and it gets underline for any
    reason, the underline gets lost<br>
    <br>
    Hope this helps to inform the RFC further.<br>
    <br>
    Smile,<br>
    Juliette<br>
    <br>
    <br>
    1: <a class="moz-txt-link-freetext" href="https://www.linkedin.com/in/nicolassteenhout/">https://www.linkedin.com/in/nicolassteenhout/</a><br>
    <br>
    <br>
  </body>
</html>

--------------090207070606070305020209--