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 16:47] – 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 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 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 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. 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.
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>
  
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 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 =====
rfc/class-naming-acronyms.1712335620.txt.gz · Last modified: 2024/04/05 16:47 by timwolla

Page Tools