Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi On 4/19/24 20:47, Bilge wrote: Not that my opinion counts for much, but I have to say I find this very odd. Good class names: Id // Identifier ID // Identity Document I understand the distinction you wish to make here, between an acronym and abbreviation, but I think it's a meaningless distinction. In this case, `Id` would be fine for "identifier", but "Identity Document" should simply be `IdentityDocument`. Whilst the distinction may seem meaningful to you, it certainly does not look that way to me; I think it would be difficult to remember and explain to someone else. Perhaps the tie breaker could be that it wouldn't be meaningful to an automated style checker, either. That is, it would be difficult to enforce this policy exception in any automated way. Why not just keep it simple and consistent here, disallowing runs of multiple upper-case letters? I have copied the example identifiers verbatim from the existing phrasing in CODING_STANDARDS.md and just moved them into the correct section according to the updated wording. However 'ID' as-in 'Identity Document' should also be 'Id' with the updated policy, which I missed. Or rather it should not be abbreviated at all. I've adjusted the examples [1], thank you for pointing this out! Best regards Tim Düsterhus [1] https://wiki.php.net/rfc/class-naming-acronyms?do=diff&rev2%5B0%5D=1712419286&rev2%5B1%5D=1713553737&difftype=sidebyside
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
On Fri, Apr 19, 2024 at 8:50 PM Bilge wrote: > On 19/04/2024 18:42, Tim Düsterhus wrote: > > The two weeks of discussion are over now, the RFC didn't receive any > substantial changes after the initial proposal, and neither was there any > significant content-related feedback after the first few days. > > As such, I plan to open the vote early next week without making further > changes to the RFC text. > > Best regards > Tim Düsterhus > > Hi Tim, > > Not that my opinion counts for much, but I have to say I find this very > odd. > > Good class names: > Id // Identifier > ID // Identity Document > > I understand the distinction you wish to make here, between an acronym and > abbreviation, but I think it's a meaningless distinction. In this case, > `Id` would be fine for "identifier", but "Identity Document" should simply > be `IdentityDocument`. Whilst the distinction may seem meaningful to you, > it certainly does not look that way to me; I think it would be difficult to > remember and explain to someone else. Perhaps the tie breaker could be that > it wouldn't be meaningful to an automated style checker, either. That is, > it would be difficult to enforce this policy exception in any automated > way. Why not just keep it simple and consistent here, disallowing runs of > multiple upper-case letters? > > Cheers, > Bilge > I was under the impression that this RFC was trying to solve exactly that, so I'm surprised to see that ID would be allowed.
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
On 19/04/2024 18:42, Tim Düsterhus wrote: The two weeks of discussion are over now, the RFC didn't receive any substantial changes after the initial proposal, and neither was there any significant content-related feedback after the first few days. As such, I plan to open the vote early next week without making further changes to the RFC text. Best regards Tim Düsterhus Hi Tim, Not that my opinion counts for much, but I have to say I find this very odd. Good class names: Id // Identifier ID // Identity Document I understand the distinction you wish to make here, between an acronym and abbreviation, but I think it's a meaningless distinction. In this case, `Id` would be fine for "identifier", but "Identity Document" should simply be `IdentityDocument`. Whilst the distinction may seem meaningful to you, it certainly does not look that way to me; I think it would be difficult to remember and explain to someone else. Perhaps the tie breaker could be that it wouldn't be meaningful to an automated style checker, either. That is, it would be difficult to enforce this policy exception in any automated way. Why not just keep it simple and consistent here, disallowing runs of multiple upper-case letters? Cheers, Bilge
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi On 4/5/24 19:00, Tim Düsterhus wrote: RFC: https://wiki.php.net/rfc/class-naming-acronyms Previous ML discussion: https://externals.io/message/120959#120959 Related discussion in PHP-FIG: https://github.com/php-fig/per-coding-style/issues/83 The two weeks of discussion are over now, the RFC didn't receive any substantial changes after the initial proposal, and neither was there any significant content-related feedback after the first few days. As such, I plan to open the vote early next week without making further changes to the RFC text. Best regards Tim Düsterhus
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi On 4/16/24 18:13, Derick Rethans wrote: None, yet. This RFC will result in changes to: The https://github.com/php/php-src/blob/536305436f44e91731bc5c86e06f137e44a01109/CODING_STANDARDS.md#L173-L211 document should probably be folded into https://github.com/php/policies/blob/main/coding-standards-and-naming.rst Indeed. I've acknowledged that in https://news-web.php.net/php.internals/123001. However doing so is out of scope for this RFC. I'm also not the appropriate person to rewrite the policies to give them a proper structure. I'm neither a technical writer, nor a native speaker of English. -- If this RFC is accepted, I'll make the proposed wording change to CODING_STANDARDS.md in php-src and append the relevant part of the RFC text to coding-standards-and-naming.rst in policies, so that it's properly accounted for when the policies in the policies repository are cleaned up as a follow-up to the policies RFC. Best regards Tim Düsterhus
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
On Fri, 5 Apr 2024, Tim Düsterhus wrote: > Hi > > I've just written up the follow-up RFC to my previous “Casing of acronyms in > class and method names” thread and I'm officially opening up the discussion > period for it. One example is the PCGOneseq128XSLRR64 mentioned above That is probably not the best example of a "readable" class name, as no matter the casing, it's not readable :-) None, yet. This RFC will result in changes to: The https://github.com/php/php-src/blob/536305436f44e91731bc5c86e06f137e44a01109/CODING_STANDARDS.md#L173-L211 document should probably be folded into https://github.com/php/policies/blob/main/coding-standards-and-naming.rst — having it in two places isn't great. cheers, Derick -- https://derickrethans.nl | https://xdebug.org | https://dram.io Author of Xdebug. Like it? Consider supporting me: https://xdebug.org/support mastodon: @derickr@phpc.social @xdebug@phpc.social
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi On 4/12/24 15:53, Saki Takamachi wrote: This isn't a BC Break in theory as class names are, for the time being, case-insensitive. Strictly speaking, this can be considered a BC Break because the string returned by `::class` changes. However, I'm not sure how much of an impact it will have. Indeed. See my email in the previous pre-RFC discussion thread: https://news-web.php.net/php.internals/121057 Best regards Tim Düsterhus
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi Gina, > This isn't a BC Break in theory as class names are, for the time being, > case-insensitive. Strictly speaking, this can be considered a BC Break because the string returned by `::class` changes. However, I'm not sure how much of an impact it will have. Regards, Saki
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
On Friday, 5 April 2024 at 18:00, Tim Düsterhus wrote: > Hi > > I've just written up the follow-up RFC to my previous “Casing of > acronyms in class and method names” thread and I'm officially opening up > the discussion period for it. > > Please find the following links for your convenience: > > RFC: https://wiki.php.net/rfc/class-naming-acronyms > Previous ML discussion: https://externals.io/message/120959#120959 > Related discussion in PHP-FIG: > https://github.com/php-fig/per-coding-style/issues/83 > Thank you for working on this! I agree that this policy change makes sense. I was wondering, however, if there should be a follow-up RFC to normalize the casing of existing classes? This isn't a BC Break in theory as class names are, for the time being, case-insensitive. I know in practice that tooling in the ecosystem normalize the names to be the one as currently defined, so it might produce diffs depending on which version of PHP the tool is ran on. The output of tests could be affected. Maybe this change is better suited for PHP 9? Best regards, Gina P. Banyard
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi On 4/7/24 06:37, Juliette Reinders Folmer wrote: I forwarded your questions from above verbatim to Nicolas and this was his response (also quoted verbatim): Thank you. > 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. While I've called the examples “extreme” myself, I don't believe they are *uncommon*. Programming is full of various acronyms and it naturally follows that some identifiers will consist of consecutive acronyms or abbreviations. I've mentioned five of them in my previous email, but added some more to the RFC as part of Saki's namespace question (SSL + CRL + URL). Here are some more acronyms that are reasonable to appear within in a single identifier. Some of them might make sense to put in a namespace hierarchy which comes with the backslash as a separator, but this does not work for method names: ASN.1 + DER AES + GCM JWT + RSA HMAC + SHA-256 API + Anything probably SAML + SSO GPU + CUDA ARM + CPU Apologize the focus on cryptographic concepts, but these case to my mind most easily :-) Best regards Tim Düsterhus
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
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
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi Tim, > Hi > > On 4/6/24 17:54, Saki Takamachi wrote: >> However, in the example from "RFC: Namespaces in bundled PHP extensions", >> the acronyms are not camelcased. e.g. `FFI\FFI`, `OpenSSL` >> In other words, the RFC can be interpreted as "excluding acronyms" >> implicitly. > > This is correct, because the current class naming policy specifies that > acronyms must be written in UPPERCASE. Thus the examples are consistent with > the current policy. > >> Just to clarify: I agree with your RFC. However, I think it is best to avoid >> vague statements where the meaning changes depending on interpretation, if >> possible. > > I've added namespaced examples: > > https://wiki.php.net/rfc/class-naming-acronyms?do=diff&rev2%5B0%5D=1712350524&rev2%5B1%5D=1712419286&difftype=sidebyside > >> In fact, due to some ambiguity in the namespace RFC, I couldn't decide >> whether BCMath's namespace should be "BcMath" or "BCMath”. > > With the current policy it should be "BCMath", if my RFC passes it should be > "BcMath". I think Bcmath would be fine as well, if you consider the extension > name to be a single word. > > Best regards > Tim Düsterhus Thanks for adding examples. Maybe it's the "namespace is implicitly part of the class name" thing that feels strange to me. Because not only classes but also functions and constants can belong to it. Regards. Saki
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi On 4/6/24 17:54, Saki Takamachi wrote: However, in the example from "RFC: Namespaces in bundled PHP extensions", the acronyms are not camelcased. e.g. `FFI\FFI`, `OpenSSL` In other words, the RFC can be interpreted as "excluding acronyms" implicitly. This is correct, because the current class naming policy specifies that acronyms must be written in UPPERCASE. Thus the examples are consistent with the current policy. Just to clarify: I agree with your RFC. However, I think it is best to avoid vague statements where the meaning changes depending on interpretation, if possible. I've added namespaced examples: https://wiki.php.net/rfc/class-naming-acronyms?do=diff&rev2%5B0%5D=1712350524&rev2%5B1%5D=1712419286&difftype=sidebyside In fact, due to some ambiguity in the namespace RFC, I couldn't decide whether BCMath's namespace should be "BcMath" or "BCMath”. With the current policy it should be "BCMath", if my RFC passes it should be "BcMath". I think Bcmath would be fine as well, if you consider the extension name to be a single word. Best regards Tim Düsterhus
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi Tim, >> Strictly speaking, namespace is neither a class nor a method, so isn't it >> outside the scope of this RFC? In fact, RFC: Class Naming makes no mention >> of namespace naming conventions at all. I asked this because there was >> mention of namespaces in the `DOM`. >> If I'm not misunderstanding something, I think I should clarify that RFCs >> also include namespaces. > > Namespaces are defined as CamelCase (i.e. upper camel case / PascalCase) in > the “Namespaces in bundled PHP Extensions” RFC: > > https://wiki.php.net/rfc/namespaces_in_bundled_extensions#proposal > > The phrasing in the RFC is intentionally worded to speak about abbreviations > and acronyms in a generic way (i.e. not specific to classes or methods). It > naturally follows that the same rules applies to acronyms in namespaces, > especially since they are effectively part of a class name. > > -- > > However I agree that it should be incorporated explicitly once the existing > policies in the policy repository have been cleaned up and rewritten as a > follow-up to the https://wiki.php.net/rfc/policy-repository RFC: > >> Once (and if) this RFC is accepted, a first new step would be to rephrase >> the text so that it reads like a policy document, instead of an RFC. The >> wording is currently exactly as in the used RFCs, without modification. > > That has not yet happened, though. However, in the example from "RFC: Namespaces in bundled PHP extensions", the acronyms are not camelcased. e.g. `FFI\FFI`, `OpenSSL` In other words, the RFC can be interpreted as "excluding acronyms" implicitly. Just to clarify: I agree with your RFC. However, I think it is best to avoid vague statements where the meaning changes depending on interpretation, if possible. In fact, due to some ambiguity in the namespace RFC, I couldn't decide whether BCMath's namespace should be "BcMath" or "BCMath”. Regards. Saki
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi On 4/6/24 17:16, Saki Takamachi wrote: Strictly speaking, namespace is neither a class nor a method, so isn't it outside the scope of this RFC? In fact, RFC: Class Naming makes no mention of namespace naming conventions at all. I asked this because there was mention of namespaces in the `DOM`. If I'm not misunderstanding something, I think I should clarify that RFCs also include namespaces. Namespaces are defined as CamelCase (i.e. upper camel case / PascalCase) in the “Namespaces in bundled PHP Extensions” RFC: https://wiki.php.net/rfc/namespaces_in_bundled_extensions#proposal The phrasing in the RFC is intentionally worded to speak about abbreviations and acronyms in a generic way (i.e. not specific to classes or methods). It naturally follows that the same rules applies to acronyms in namespaces, especially since they are effectively part of a class name. -- However I agree that it should be incorporated explicitly once the existing policies in the policy repository have been cleaned up and rewritten as a follow-up to the https://wiki.php.net/rfc/policy-repository RFC: Once (and if) this RFC is accepted, a first new step would be to rephrase the text so that it reads like a policy document, instead of an RFC. The wording is currently exactly as in the used RFCs, without modification. That has not yet happened, though. Best regards Tim Düsterhus
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi Tim, > I've just written up the follow-up RFC to my previous “Casing of acronyms in > class and method names” thread and I'm officially opening up the discussion > period for it. > > Please find the following links for your convenience: > > RFC: https://wiki.php.net/rfc/class-naming-acronyms > Previous ML discussion: https://externals.io/message/120959#120959 > Related discussion in PHP-FIG: > https://github.com/php-fig/per-coding-style/issues/83 > > I'd like to thank Larry and Niels for proof-reading the RFC and making direct > wording improvements (check the edit history for details). Strictly speaking, namespace is neither a class nor a method, so isn't it outside the scope of this RFC? In fact, RFC: Class Naming makes no mention of namespace naming conventions at all. I asked this because there was mention of namespaces in the `DOM`. If I'm not misunderstanding something, I think I should clarify that RFCs also include namespaces. Regards. Saki
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
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
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
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
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
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
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
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
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
Hi Juliette On 05/04/2024 20:01, Juliette Reinders Folmer wrote: > On 5-4-2024 19:48, Niels Dossche wrote: >>> I support this proposal. >>> If accepted, I'll make the necessary changes to ext-dom and ext-xsl to >>> comply with the new policy. > Niels: just wondering what changes you are referring to ? The RFC explicitly > states "Existing class and method names in released versions are not > affected"... ? > I refer to the changes listed in section "Adjusting class & method names added in PHP 8.4". These fall under unreleased versions, as no PHP 8.4 releases have been made so far. > > Smile, > Juliette Kind regards Niels
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
On 5-4-2024 19:48, Niels Dossche wrote: On 05/04/2024 19:00, Tim Düsterhus wrote: I've just written up the follow-up RFC to my previous “Casing of acronyms in class and method names” thread and I'm officially opening up the discussion period for it. Please find the following links for your convenience: RFC: https://wiki.php.net/rfc/class-naming-acronyms Previous ML discussion: https://externals.io/message/120959#120959 Related discussion in PHP-FIG: https://github.com/php-fig/per-coding-style/issues/83 Tim, 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. 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. I support this proposal. If accepted, I'll make the necessary changes to ext-dom and ext-xsl to comply with the new policy. Niels: just wondering what changes you are referring to ? The RFC explicitly states "Existing class and method names in released versions are not affected"... ? Smile, Juliette
Re: [PHP-DEV] [RFC] Casing of acronyms in class and method names
On 05/04/2024 19:00, Tim Düsterhus wrote: > Hi > > I've just written up the follow-up RFC to my previous “Casing of acronyms in > class and method names” thread and I'm officially opening up the discussion > period for it. > > Please find the following links for your convenience: > > RFC: https://wiki.php.net/rfc/class-naming-acronyms > Previous ML discussion: https://externals.io/message/120959#120959 > Related discussion in PHP-FIG: > https://github.com/php-fig/per-coding-style/issues/83 > > I'd like to thank Larry and Niels for proof-reading the RFC and making direct > wording improvements (check the edit history for details). > > Best regards > Tim Düsterhus I support this proposal. If accepted, I'll make the necessary changes to ext-dom and ext-xsl to comply with the new policy. Cheers Niels
