[RFC] Casing of acronyms in class and method names

2 years ago by Niels Dossche — view source — reply

unread

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

2 years ago by Juliette Reinders Folmer — view source — reply

unread

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

2 years ago by Niels Dossche — view source — reply

unread

Hi Juliette

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

2 years ago by tim@bastelstu.be — view source — reply

unread

Hi

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

2 years ago by Larry Garfield — view source — reply

unread

Hi

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

2 years ago by Juliette Reinders Folmer — view source — reply

unread

Hi

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/

2 years ago by tim@bastelstu.be — view source — reply

unread

Hi

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:

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.

PDO ODBC

which is "PHP Data Object Open Database Connectivity", but no one writes
those acronyms out in full.

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.

UUID v4

Taken from Ben Ramsey’s UUID library:
https://github.com/ramsey/uuid/tree/4.x/src/Rfc4122

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

2 years ago by Juliette Reinders Folmer — view source — reply

unread

Hi

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:

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.

PDO ODBC

which is "PHP Data Object Open Database Connectivity", but no one
writes those acronyms out in full.

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.

UUID v4

Taken from Ben Ramsey’s UUID library:
https://github.com/ramsey/uuid/tree/4.x/src/Rfc4122

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

2 years ago by tim@bastelstu.be — view source — reply

unread

Hi

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

2 years ago by Saki Takamachi — view source — reply

unread

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

2 years ago by tim@bastelstu.be — view source — reply

unread

Hi

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

2 years ago by Saki Takamachi — view source — reply

unread

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

2 years ago by tim@bastelstu.be — view source — reply

unread

Hi

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

2 years ago by Saki Takamachi — view source — reply

unread

Hi Tim,

Hi

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

2 years ago by Gina P. Banyard — view source — reply

unread

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

2 years ago by Saki Takamachi — view source — reply

unread

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

2 years ago by tim@bastelstu.be — view source — reply

unread

Hi

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

2 years ago by Derick Rethans — view source — reply

unread

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

2 years ago by tim@bastelstu.be — view source — reply

unread

Hi

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

2 years ago by tim@bastelstu.be — view source — reply

unread

Hi

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

2 years ago by Bilge — view source — reply

unread

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

2 years ago by Lynn — view source — reply

unread

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.

2 years ago by tim@bastelstu.be — view source — reply

unread

Hi

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