rfc:deque_straw_poll

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:deque_straw_poll [2022/01/09 18:49] tandrerfc:deque_straw_poll [2022/01/26 14:43] (current) tandre
Line 1: Line 1:
 ====== Straw poll: Naming pattern to use for Deque ====== ====== Straw poll: Naming pattern to use for Deque ======
-  * Version: 0.1+  * Version: 0.3
   * Date: 2022-01-05   * Date: 2022-01-05
   * Author: Tyson Andre, tandre@php.net   * Author: Tyson Andre, tandre@php.net
-  * Status: Under Discussion+  * Status: Closed
   * First Published at: http://wiki.php.net/rfc/deque_straw_poll   * First Published at: http://wiki.php.net/rfc/deque_straw_poll
  
Line 16: Line 16:
 but offers guidance in choosing namespace names and allows for using namespaces in new categories of functionality. but offers guidance in choosing namespace names and allows for using namespaces in new categories of functionality.
  
-The planned options are:+The options in this straw poll are:
  
   * ''\Deque'', the name currently used in the RFC/implementation. See https://wiki.php.net/rfc/deque#global_namespace \\ This was my preference because it was short, making it easy to remember and convenient to use.   * ''\Deque'', the name currently used in the RFC/implementation. See https://wiki.php.net/rfc/deque#global_namespace \\ This was my preference because it was short, making it easy to remember and convenient to use.
  
  
-  * ''\Collections\Deque''the singular form is proposed because this might grow long-term to contain not just collections, but also functionality related to collections in the future(e.g. helper classes for building classes (e.g. ImmutableSequenceBuilder for building an ImmutableSequence)global functionstraits/interfaces, collections of static methods, etc. \\ (especially since https://wiki.php.net/rfc/namespaces_in_bundled_extensions prevents more than one level of namespaces)+  * ''\Collections\Deque''seems like a reasonable choice of name for collections (Dequeand possible future additions such as VectorSet, MapSorted Sets/Maps, etc. https://wiki.php.net/rfc/namespaces_in_bundled_extensions also allows using sub-namespaces and that may be used for things that aren't strictly collections, e.g. ''Collections\Builder\SomethingBuilder'' or functions operating on collections.
  
-  * ''\SplDeque'', similar to datastructures added to the Spl in PHP 5.3. \\ (I don't prefer that name because SplDoublyLinkedList, SplStack, and SplQueue are subclasses of a doubly linked list with poor performance, and this name would easily get confused with them. Also, historically, none of the functionality with that naming pattern has been final. \\ However, good documentation (e.g. suggesting *Deque instead where possible in the manual) would make that less of an issue.) \\ \\ See https://wiki.php.net/rfc/deque#lack_of_name_prefix (and arguments for https://externals.io/message/116100#116111)+  * ''\SplDeque'', similar to datastructures added to the Spl in PHP 5.3. \\ (I don't prefer that name because SplDoublyLinkedList, SplStack, and SplQueue are subclasses of a doubly linked list with poor performance (accessing the offset in the middle of a linked list requires traversing half the linked list, for example), and this name would easily get confused with them. Also, historically, none of the functionality with that naming pattern has been final. \\ However, good documentation (e.g. suggesting *Deque instead where possible in the manual) would make that less of an issue.) \\ \\ See https://wiki.php.net/rfc/deque#lack_of_name_prefix (and arguments for https://externals.io/message/116100#116111)
  
 While there is considerable division in whether or not members of internals want to adopt namespaces, While there is considerable division in whether or not members of internals want to adopt namespaces,
Line 55: Line 55:
 Those would differ from existing classes in the spl in several ways: Those would differ from existing classes in the spl in several ways:
  
-  * Be final classes and avoid unpredictable behaviors. Extensibility has been a cause of performance issues and unexpected bugs historically, and makes code harder to reason about.+  * Be final classes (or have final methods when extensibility is needed for core functionality) and avoid unpredictable behaviors. Extensibility has been a cause of performance issues and unexpected bugs historically, and makes code harder to reason about. \\ For example, [[rfc:deque#benchmarks|Deque would be memory and time efficient compared to SplDoublyLinkedList]]
   * Forbid dynamic properties.   * Forbid dynamic properties.
-  * [[rfc|deque#benchmarks|Deque would be memory and time efficient compared to SplDoublyLinkedList]] 
  
 ===== Discussion ===== ===== Discussion =====
Line 63: Line 62:
 ==== Arguments for/against Deque ==== ==== Arguments for/against Deque ====
  
-This was my preference **because it was short, making it easy to remember and convenient to use.** The majority of existing functionality uses the global namespace.+The global namespace was my preference **because it was short, making it easy to remember and convenient to use.** The majority of existing internal classes use the global namespace.
  
 https://wiki.php.net/rfc/namespaces_in_bundled_extensions recently passed. https://wiki.php.net/rfc/namespaces_in_bundled_extensions recently passed.
 It permits using the same namespace that is already used in an extension (in this case, the global namespace), It permits using the same namespace that is already used in an extension (in this case, the global namespace),
 but offers guidance in choosing namespace names and allows for using namespaces in new categories of functionality. but offers guidance in choosing namespace names and allows for using namespaces in new categories of functionality.
 +
 +My reason for proposing ''Deque'' in the global namespace is:
 +
 +<blockquote>
 +This maintains consistency with the namespace used for general-purpose collections already in the SPL (as well as relatively recent additions such as ''WeakReference'' (PHP 7.4) and ''WeakMap'' (PHP 8.0)). Other recent additions to PHP such as ''ReflectionIntersectionType'' in PHP 8.1 have also continued to use the global namespace when adding classes with functionality related to other classes.
 +
 +Additionally, prior polls for namespacing choices of other datastructure functionality showed preferences for namespacing and not namespacing were evenly split [[rfc:cachediterable_straw_poll#namespace_choices|in a straw poll for a new iterable type]].
 +
 +Introducing a new namespace for data structures would also raise the question of whether existing datastructures should be moved to that new namespace (for consistency), and that process of moving namespaces would (if started):
 +
 +    - Raise the amount of work needed for end users or library/framework/application authors to migrate to new PHP versions.
 +    - Cause confusion and inconvenience for years about which namespace can or should be used in an application (''SplObjectStorage'' vs ''Xyz\SplObjectStorage''), especially for developers working on projects supporting different php version ranges.
 +    - Prevent applications/libraries from easily supporting as wide of a range of php versions.
 +    - Cause serialization/unserialization issues when migrating to different php versions, if the old or new class name in the serialized data did not exist in the other php version and was not aliased. For example, if the older PHP version could not ''unserialize()'' ''Xyz\SplObjectStorage'' and would silently create a [[https://www.php.net/manual/en/language.oop5.serialization.php#language.oop5.serialization|__PHP_Incomplete_Class_Name]] without any warnings or notices.
 +</blockquote>
  
 https://externals.io/message/116100#116111 https://externals.io/message/116100#116111
Line 98: Line 112:
 This seems like a reasonable choice of name for collections (Deque, and possible future additions such as Vector, Set, Map, Sorted Sets/Maps, etc. This seems like a reasonable choice of name for collections (Deque, and possible future additions such as Vector, Set, Map, Sorted Sets/Maps, etc.
 https://wiki.php.net/rfc/namespaces_in_bundled_extensions also allows using sub-namespaces and that may be used for things that aren't strictly collections, e.g. ''Collections\Builder\SomethingBuilder''. https://wiki.php.net/rfc/namespaces_in_bundled_extensions also allows using sub-namespaces and that may be used for things that aren't strictly collections, e.g. ''Collections\Builder\SomethingBuilder''.
 +
 +Levi Morrison mentions in https://externals.io/message/116100#116119
 +
 +<blockquote>
 +Given that I've suggested the most common options for these across
 +many languages, it (''Collections\'') shouldn't be very controversial. The worst bit
 +seems like picking the namespace "Collections" as this will break at
 +least one package: https://github.com/danielgsims/php-collections. We
 +should suggest that they vendor it anyway, as "collections" is common
 +e.g. "Ramsey\Collections", "Doctrine\Common\Collections". I don't see
 +a good alternative here to "Collections", as we haven't agreed on very
 +much on past namespace proposals.
 +</blockquote>
 +
 +(note that https://github.com/danielgsims/php-collections does not declare ''Collections\Deque'' anywhere: https://github.com/danielgsims/php-collections/tree/2.X/src)
 +
 +=== Why plural? ===
  
 This proposed namespace is plural because: This proposed namespace is plural because:
  
   * ''Collections\Deque'' feels more natural to write than ''Collection\Deque''.   * ''Collections\Deque'' feels more natural to write than ''Collection\Deque''.
-  * Other languages have also used plural for their standard libraries: https://docs.python.org/3/library/collections.html https://doc.rust-lang.org/std/collections/index.html +  * Other languages have also used plural for their standard libraries: https://docs.python.org/3/library/collections.html https://doc.rust-lang.org/std/collections/index.html and https://docs.oracle.com/javase/7/docs/api/java/util/Collections.html 
-  * php-ds also stands for "PHP Data Structures" - https://github.com/php-ds - so a Collections namespace may be used for a ''collections'' PHP module to match the namespace. (https://wiki.php.net/rfc/namespaces_in_bundled_extension)+  * php-ds also stands for the plural "PHP Data Structures" - https://github.com/php-ds - so a Collections namespace may be used for a ''collections'' PHP module to match the namespace. (https://wiki.php.net/rfc/namespaces_in_bundled_extension)
  
 ==== Arguments for/against SplDeque ==== ==== Arguments for/against SplDeque ====
Line 111: Line 142:
 I believe the name ''SplDeque'' would be a source of frustration and performance issues for users, though. a ''SplDeque'' would be confused way too easily with SplDoublyLinkedList and it subclasses SplQueue/SplStack - switching from a SplDeque to a SplStack (linked list) would suddenly make operations such as ArrayAccess much slower and use more memory due to needing to traverse a linked list. See https://wiki.php.net/rfc/deque#benchmarks I believe the name ''SplDeque'' would be a source of frustration and performance issues for users, though. a ''SplDeque'' would be confused way too easily with SplDoublyLinkedList and it subclasses SplQueue/SplStack - switching from a SplDeque to a SplStack (linked list) would suddenly make operations such as ArrayAccess much slower and use more memory due to needing to traverse a linked list. See https://wiki.php.net/rfc/deque#benchmarks
  
-  * Also, people may not realize there's a difference in performance that would be a reason to migrate existing Spl data structures to ''*Queue''. +  * Also, people may not realize there's a difference in performance that would be a reason to migrate existing Spl data structures to ''*Deque'' or to adopt ''*Deque'' in the first place.
  
 ===== Vote ===== ===== Vote =====
 +
 +Voting started on 2022-01-12 and ended on 2022-01-26.
  
 This vote will influence the name choice for the [[rfc:Deque|Deque RFC]] This vote will influence the name choice for the [[rfc:Deque|Deque RFC]]
Line 165: Line 197:
   - https://externals.io/message/116112 "(Planned) Straw poll: Naming pattern for ''*Deque''"   - https://externals.io/message/116112 "(Planned) Straw poll: Naming pattern for ''*Deque''"
  
 +the plural form is proposed because this might grow long-term to contain not just collections, but also functionality related to collections in the future(e.g. helper classes for building classes (e.g. ImmutableSequenceBuilder for building an ImmutableSequence), global functions, traits/interfaces, collections of static methods, etc. \\ (especially since https://wiki.php.net/rfc/namespaces_in_bundled_extensions prevents more than one level of namespaces)
 +
 +===== Changelog =====
  
 +0.2: Fix description of Collections\Deque naming choice in the introduction.
 +0.3: Change introduction sections
rfc/deque_straw_poll.txt · Last modified: 2022/01/26 14:43 by tandre