[wp-trac] [WordPress Trac] #63558: Code Quality: Add `: void` return types to non-breaking method signatures

[WordPress Trac]

#63558: Code Quality: Add `: void` return types to non-breaking method signatures
-------------------------+-----------------------------
 Reporter:  justlevine   |      Owner:  (none)
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  General      |    Version:
 Severity:  normal       |   Keywords:
  Focuses:               |
-------------------------+-----------------------------
 This ticket proposes implementing explicit `: void` return type
 declarations to existing WordPress method and functions.


 === Background ===

 > Type declaration usage has the following restrictions based on the
 minimum required PHP version of an application, whether it is WordPress
 Core, a plugin or a theme:
 > [...]
 > - The iterable and void type declarations cannot be used until the
 minimum PHP version is PHP 7.1 or higher. The void type can only be used
 as a return type.

     - https://developer.wordpress.org/coding-standards/wordpress-coding-
 standards/php/

 > `@return`: Should contain all possible return types and a description
 for each. Use a period at the end. Note: `@return void` should not be used
 outside the default bundled themes and the PHP compatibility shims
 included in WordPress Core.

     - https://developer.wordpress.org/coding-standards/inline-
 documentation-standards/php/

 > Code refactoring should not be done just because we can.

     - https://make.wordpress.org/core/handbook/contribute/code-
 refactoring/

 === Justifications for refactor ===

 1. Minimum Requirements surpassed: WP's current minimum is 7.2+ (with 7.4
 slated for 6.9)
 2. Improved Documentation: Unlike other return types, we don't note this
 in the doc-block. Adding it to the method both documents the `@void` with
 no extra lines. Plus, unlike a PHPDoc block, method signatures can't be
 mistaken or fall out of date
 3. Improved Developer Experience:
   - IDEs and tooling (including AI) can provide better autocomplete, error
 detection, and most-importantly type-safety guarantees - benefiting both
 extenders and core contributors.
   - Helps us with work on Codebase modernization and implementing PHPStan
 4. Negligible risk of invalidating other work: Since we don't refactor
 unnecessarily and generally avoid breaking changes, there isn't really
 much that can cause a diff conflict on a method signature - especially if
 we follow some guidelines.

 === Proposed scope/strategy ===

 1. Only target: `private` and `final` methods, and global functions -
 since the signature change won't break compatibility.
 2. Only update the signature to add a `: void` return type. While many of
 the arguments made in this ticket can be used to justify updating other
 return types, due to current lack of codebase type-safety these are much
 harder to verify.
 3. Only implement on methods that should actually return `void`. There's a
 lot of preexisting null/void coercion that will easier to untangle once
 our type safety efforts are further along.
 4. Don't update the method contents. Same reasons as the previous point.
 5. Make the changes across multiple PRs. This is more about making sure
 the PRs get merged quickly, than potential conflicts from other PRs. The
 longer it takes between creation and merge for a particular file or class,
 the more likely new methods may be added to that file that should also
 have a `void` return signature, but if a contributor sees other methods
 using return types, they'll be more likely to add them to their new code,
 saving some work down the line.

 === Next Steps ===
 1. I'm going to make a PR targeting a Class or two based on the above,
 that can serve as proof of concept - and assuming this proposal is
 accepted hopefully get it merged both for here and as part of our PHPStan
 efforts. Will wait for that acceptance before spending time updating other
 classes and encouraging others to join on the refactor effort.
 2. While we shouldn't "enforce it" yet on new code (iirc WPCS doesn't let
 you allow-list tech-debt, just manually ignore), we should write a Make
 post to encourage contributors/reviewers encouraging them to start using
 `void` return types.
 3. A future conversation about updating WPCS to enforce the use of `:
 void` when appropriate can happen at any point. It can be enforced on new
 code alone with PHPStan once merge (baselining methods we haven't updated
 yet), and PHPCS can autofix on once the existing codebase has been
 audited/updated. (PHPCS relies on the phpdoc type which as noted above
 isnt accurate in many places).

 === Related ===
 - #61175
 - #63268
 - #63166

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/63558>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform