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 14:02] – timwollarfc: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 24: Line 25:
 === It decreases readability === === It decreases readability ===
  
-And it especially does 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.+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.
  
 Likewise <php>PDOODBC</php> is much harder to parse than <php>PdoOdbc</php>. Likewise <php>PDOODBC</php> is much harder to parse than <php>PdoOdbc</php>.
Line 30: 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.
  
-=== Several commonly used userland libraries make a different choice ===+=== The userland convention is mostly MixedCase === 
 + 
 +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 40: 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 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 84: 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 98: 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 111: 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 121: 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 136: 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 177: 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 188: Line 210:
 ===== Implementation ===== ===== Implementation =====
  
-n/a+  * https://github.com/php/php-src/pull/14169 
 +  * https://github.com/php/policies/pull/7
  
 ===== References ===== ===== References =====
Line 194: 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.1712325749.txt.gz · Last modified: 2024/04/05 14:02 by timwolla

Page Tools