rfc:class-naming-acronyms

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:class-naming-acronyms [2024/04/05 15:43] – Slight rewording, add accessibility argument, mention FIG. crellrfc:class-naming-acronyms [2024/05/08 18:55] (current) – Link implementation PRs timwolla
Line 3: Line 3:
   * Date: 2024-04-05   * Date: 2024-04-05
   * Author: Tim Düsterhus, timwolla@php.net   * Author: Tim Düsterhus, timwolla@php.net
-  * Status: Draft+  * Status: Accepted 
 +  * Implementation: https://github.com/php/php-src/pull/14169, https://github.com/php/policies/pull/7
   * First Published at: http://wiki.php.net/rfc/class-naming-acronyms   * First Published at: http://wiki.php.net/rfc/class-naming-acronyms
  
Line 25: Line 26:
  
 It is well-established in accessibility circles that ALL CAPS text is harder to read than Mixed Case, as mixed case provides greater vertical variation between letters, making it easier to read, especially for people with various reading disorders. It is well-established in accessibility circles that ALL CAPS text is harder to read than Mixed Case, as mixed case provides greater vertical variation between letters, making it easier to read, especially for people with various reading disorders.
 +
 +Most accessibility organizations recommend against ALL CAPS.  For example:
 +
 +  * [[https://w3c.github.io/low-vision-a11y-tf/requirements.html#capitalization|W3C]]
 +  * [[https://accessibility.huit.harvard.edu/design-readability|Harvard University]]
 +  * [[https://www.a11yproject.com/posts/how-to-accessible-heading-structure/#all-caps|The A11y Project]]
  
 That issue is amplified if multiple acronyms follow each other. One example is the <php>PCGOneseq128XSLRR64</php> mentioned above: It’s not clear that ''XSL'' (XorShiftLow) and ''RR'' (RandomlyRotate) are two different acronyms. That issue is amplified if multiple acronyms follow each other. One example is the <php>PCGOneseq128XSLRR64</php> mentioned above: It’s not clear that ''XSL'' (XorShiftLow) and ''RR'' (RandomlyRotate) are two different acronyms.
Line 32: Line 39:
 Another example might be JavaScript’s <php>XMLHttpRequest</php> which incidentally mixes both variants. According to the class naming RFC it would need to be called <php>XMLHTTPRequest</php>, resulting in 8 consecutive uppercase characters. Another example might be JavaScript’s <php>XMLHttpRequest</php> which incidentally mixes both variants. According to the class naming RFC it would need to be called <php>XMLHTTPRequest</php>, resulting in 8 consecutive uppercase characters.
  
-=== The user-space convention is mostly MixedCase ===+=== The userland convention is mostly MixedCase ===
  
-Although there is no formal standard in user-space for handling initialisms, the most widely used convention is to only capitalize the first letter.  For example:+Although there is no formal standard in userland for handling initialisms, the most widely used convention is to only capitalize the first letter.  For example:
  
   * Symfony's HttpFoundation: https://github.com/symfony/symfony/tree/6.4/src/Symfony/Component/HttpFoundation   * Symfony's HttpFoundation: https://github.com/symfony/symfony/tree/6.4/src/Symfony/Component/HttpFoundation
Line 44: Line 51:
   * Flysystem is a little inconsistent, but has 'Ftp': https://github.com/thephpleague/flysystem/tree/3.x/src/Ftp   * Flysystem is a little inconsistent, but has 'Ftp': https://github.com/thephpleague/flysystem/tree/3.x/src/Ftp
   * PHPUnit is a little inconsistent, but has 'Xml' and 'Json': https://github.com/sebastianbergmann/phpunit/tree/main/src/Util   * PHPUnit is a little inconsistent, but has 'Xml' and 'Json': https://github.com/sebastianbergmann/phpunit/tree/main/src/Util
-  * Doctrine is also a little inconsistent, but has 'Dsn' and 'Sql' (but also 'SQL'): https://github.com/doctrine/dbal/tree/3.6.x/src/Schema/Visitor and https://github.com/doctrine/dbal/blob/3.6.x/src/Tools/DsnParser.php+  * Doctrine is also a little inconsistent, but has 'Dsn' and 'Sql' (but also 'SQL'): https://github.com/doctrine/dbal/tree/3.9.x/src/Schema/Visitor and https://github.com/doctrine/dbal/blob/3.9.x/src/Tools/DsnParser.php
  
-Although this RFC has no direct impact on user-space code, normalizing conventions between Internals and user-space has many benefits.  The PER-CS working group, part of the PHP-FIG, has been asked to adopt a standard for initialisms and would likely follow suit with this RFC if passed.+Although this RFC has no direct impact on userland code, normalizing conventions between Internals and userland has many benefits.  The PER-CS working group, part of the PHP-FIG, has been asked to adopt a standard for initialisms and would likely follow suit with this RFC if passed.
  
 ===== Proposal ===== ===== Proposal =====
Line 90: Line 97:
 Url Url
 BtreeMap // B-tree Map BtreeMap // B-tree Map
-Id // Identifier +UserId // User Identifier
-ID // Identity Document+
 Char // Character Char // Character
 Intl // Internationalization Intl // Internationalization
 +Ssl\Certificate
 +Ssl\Crl // Certificate Revocation List
 +Ssl\CrlUrl
 </code> </code>
  
Line 104: Line 113:
 URL URL
 BTreeMap BTreeMap
-ID // Identifier+UserID // User Identifier
 CHAR CHAR
 INTL INTL
 +SSL\Certificate
 +SSL\CRL
 +SSL\CRLURL
 </code> </code>
  
-==== Adjusting class names added in PHP 8.4 ====+==== Adjusting class & method names added in PHP 8.4 ====
  
 The [[domdocument_html5_parser|DOM HTML5 parsing and serialization RFC]] introduced new class names and method names that violate the updated naming policy, should this RFC be accepted. As part of this RFC, the following changes will be made: The [[domdocument_html5_parser|DOM HTML5 parsing and serialization RFC]] introduced new class names and method names that violate the updated naming policy, should this RFC be accepted. As part of this RFC, the following changes will be made:
Line 117: Line 129:
   * DOM\HTMLCollection -> Dom\HTMLCollection (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the name)   * DOM\HTMLCollection -> Dom\HTMLCollection (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the name)
   * DOM\CDATASection -> Dom\CDATASection (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the name)   * DOM\CDATASection -> Dom\CDATASection (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the name)
-  * DOM\HTMLDocument -> Dom\HtmlDocument +  * DOM\HTMLDocument -> Dom\HTMLDocument (Justification: Consistency with XMLDocument) 
-  * DOM\XMLDocument -> Dom\XmlDocument+  * DOM\XMLDocument -> Dom\XMLDocument (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the name)
   * DOM\XPath -> Dom\XPath (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the XPath interfaces that use this casing)   * DOM\XPath -> Dom\XPath (Justification: The [[https://dom.spec.whatwg.org/|DOM Standard]] specifies the XPath interfaces that use this casing)
   * DOM\Implementation::createHTMLDocument() -> Dom\Implementation::createHtmlDocument()   * DOM\Implementation::createHTMLDocument() -> Dom\Implementation::createHtmlDocument()
Line 127: Line 139:
   * DOM\Document::relaxNGValidate() -> Dom\Document::relaxNgValidate()   * DOM\Document::relaxNGValidate() -> Dom\Document::relaxNgValidate()
   * DOM\Document::relaxNGValidateSource() -> Dom\Document::relaxNgValidateSource()   * DOM\Document::relaxNGValidateSource() -> Dom\Document::relaxNgValidateSource()
-  * DOM\HTMLDocument::saveXML() -> Dom\HtmlDocument::saveXml() +  * DOM\HTMLDocument::saveXML() -> Dom\HTMLDocument::saveXml() 
-  * DOM\HTMLDocument::saveXMLFile() -> Dom\HtmlDocument::saveXmlFile() +  * DOM\HTMLDocument::saveXMLFile() -> Dom\HTMLDocument::saveXmlFile() 
-  * DOM\HTMLDocument::saveHTML() -> Dom\HtmlDocument::saveHtml() +  * DOM\HTMLDocument::saveHTML() -> Dom\HTMLDocument::saveHtml() 
-  * DOM\HTMLDocument::saveHTMLFile() -> Dom\HtmlDocument::saveHtmlFile() +  * DOM\HTMLDocument::saveHTMLFile() -> Dom\HTMLDocument::saveHtmlFile() 
-  * DOM\XMLDocument::saveXML() -> Dom\XmlDocument::saveXml() +  * DOM\XMLDocument::saveXML() -> Dom\XMLDocument::saveXml() 
-  * DOM\XMLDocument::saveXMLFile() -> Dom\XmlDocument::saveXmlFile()+  * DOM\XMLDocument::saveXMLFile() -> Dom\XMLDocument::saveXmlFile()
  
 For the [[improve_callbacks_dom_and_xsl|Improve callbacks in ext/dom and ext/xsl RFC]] the following changes will be made: For the [[improve_callbacks_dom_and_xsl|Improve callbacks in ext/dom and ext/xsl RFC]] the following changes will be made:
Line 142: Line 154:
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
  
-Existing classnames in released versions are not affected, thus there are not backwards incompatible changes. This is a policy RFC.+Existing class and method names in released versions are not affected, thus there are not backwards incompatible changes. This is a policy RFC.
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
Line 183: Line 195:
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
-Include these so readers know where you are heading and can discuss the proposed voting options.+ 
 +<doodle title="Adopt the updated class naming policy and adjust the new names introduced in PHP 8.4?" auth="timwolla" voteType="single" closed="yes" closeon="2024-05-06T14:00:00Z"> 
 +   * yes 
 +   * no 
 +</doodle>
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
Line 194: Line 210:
 ===== Implementation ===== ===== Implementation =====
  
-n/a+  * https://github.com/php/php-src/pull/14169 
 +  * https://github.com/php/policies/pull/7
  
 ===== References ===== ===== References =====
Line 200: Line 217:
   * [[class-naming|Class Naming RFC]]   * [[class-naming|Class Naming RFC]]
   * Prior mailing list discussion: https://externals.io/message/120959#120959   * Prior mailing list discussion: https://externals.io/message/120959#120959
 +  * Discussion in PHP-FIG for PER-CS: https://github.com/php-fig/per-coding-style/issues/83
  
 ===== Rejected Features ===== ===== Rejected Features =====
  
 n/a n/a
rfc/class-naming-acronyms.1712331834.txt.gz · Last modified: 2024/04/05 15:43 by crell

Page Tools