When documenting PHP, there are two schools of thought regarding the use of @return tags in DocBlocks when the function or method being documented doesn’t actually have a return keyword:
- Don’t include a
@returntag. - Include a
@returntag with a type ofvoid.
I’m not saying that either is wrong, but the second-one is most definitely as far from correct as you can get.
Let’s look at the reasons.
Logic and Standards
The @return tag documentation for phpDocumentor, the de facto standard for PHP documentation says:
The @return tag is used to document the return value of functions or methods.
In our scenario, there is no explicit return value, so there shouldn’t be a @return tag, just the same as you wouldn’t include a @param tag when there are no arguments, or a @global tag when there’s no global variable being used.
The Wikipedia page for PHPDoc states that the @return tag should not be used for a void / no return value.
Furthermore, the source code examples 2 and 3 on the phpdoc.org website clearly omit the @return tag when there is no return keyword.
The draft PHPDoc PSR, a document which hopes to become the de jure standard, says it is optional, but this is only so that it stays somewhat compatible with the existing (poor) real world practises.
Void !== Null
The PHP Manual clearly states that:
If the return() is omitted the value NULL will be returned.
Null and void are not the same, so by including @return void you’re actually giving wrong documentation, which is worse than no documentation.
Void is not a data type
The phpDocumentor documentation goes on to say:
The datatype should be a valid PHP type (int, string, bool, etc), a class name for the type of object returned, or simply “mixed”.
As noted in the PHP manual, void is not a valid PHP type. At best, it’s a pseudo-type, and only used to describe PHP functions for the purposes of documenting the C code that PHP is actually written in. It’s not suitable for documenting PHP code.
Code Dilution
There’s little benefit having a tag that says that nothing is returned, when you can save a line of comment code and know that the return keyword is not present when the @return tag is not present.
IDEs
An IDE such as Netbeans, Zend Studio, Eclipse, PHPStorm can often generate the basic documentation when a shortcut like /** followed by the Enter key is typed right above an entity that can have documentation. The default behaviour for the ones I’ve used is that these only include the @return tag in the documentation when the return keyword is present.
The post Why @return void is wrong in PHP documentation Putting an end to a bad practice appeared first on Gary's Code.
