Create/Find sniffs to check for functions with inconsistent return types

[jrfnl]

Sniff specification:

Goal:

Prevent functions from being declared with:

• A void return in combination with another return type. (Forbidden)
  * @return \My_Object|void
• Three or more different return types. (Refactor advised)
  * @return object|int|bool

Rationale:

Each of the above situations makes unit testing functions more difficult and should be avoided.

Notes for implementation:

• This may need to be implemented in separate sniffs checking the various points. Whether this should be one sniff or several will clarify itself once working on it.
• The sniff(s) would need to do several things:
  • Check if the function declared contains return statements and whether the type of each return can be determined.
  • Check if the function declared has a function DocBlock, if the function DocBlock contains a @return tag and if so, what the documented return types are.
  • [TO BE IMPLEMENTED LATER] Check if the function declared has a PHP 7+ return type declaration.
  • Combine and compare the results of the above two (three) checks to see if an error should be thrown.

Open questions:

• Should an explicit null return when combined in a function which can also return different types, trigger an error ?
• Is an explicit null return allowed and should it be documented as null or as void ?
• Will PHP 7.1 nullable return types be allowed (if and when) ?

Refs:

• https://yoast.slack.com/archives/C0361PEK4/p1535629425000100

To Do:

• Check if a sniff already exists for this in PHPCS itself or in another external standard which could be added as a dependency.
• If so, add the dependency and add the sniff to the ruleset.
  • Check that the sniff is written in a code-style independent way and if not, improve the external sniff.
  • Check if the sniff covers all three aspects mentioned above and if not, either see about improving the external sniff or create a secondary YoastCS sniff to address the remaining aspects.
• If not, write the sniff.