Why @return void is wrong in PHP documentation Putting an end to a bad practice

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:

  1. Don’t include a @return tag.
  2. Include a @return tag with a type of void.

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.

Comments

  1. Hello Gary,

    I’ll be the devil advocate here but I would say that adding the @return void is actually good practice.
    The reader would now for sure that there is nothing returned. No return should mean that nothing is returned in the best of worlds but is not the case in our everyday life cause the the author of the code might have simply forgotten the @return.
    Although I totally agree with the points you have made, I still think @return void is better just for readability/precision.

    • Hi zeflasher,

      Devil’s advocates promotes discussion, so that’s fine :-)

      Documentation generators can easily detect if there’s a return keyword in the code, but no @return tag in the docs – the same as they can detect missing, incorrectly named or incorrectly typed (when hinted) params versus @param in the docs. If you trust them to have done a decent job with writing the docs, then they should be trusted to add a @return where needed too.

      In Netbeans at least, and maybe other IDEs, as soon as you type /** and hit enter before a function that has a return, then @return appears in the doc template – if there’s no return keyword, then it doesn’t appear. There’s no excuse for the developer to “forget”.

      I think the trouble, as you’ve demonstrated, comes down to people stuck in their own ways – you totally agree with my points, but aren’t willing to agree with the conclusion?

  2. Hey Gary,

    You do have a valid point of null != void. However, like zeflasher I do agree it is a good coding practice. In our company we have a sniffer that detects if someone returns without declaring a return, but I wouldn’t say that the case is true for more companies.

    Additionally if you view the ZF Coding Standards Release Candidate (which is what we base on coding standards on), it does touch on this subject:

    http://framework.zend.com/wiki/display/ZFDEV/ZF+Coding+Standards+%28RC%29

    “If the function does not return any value then the return value must be set to void”

    “There has been discussions in past about void versus null. Keep in mind that these two are not the same. Null means that a empty variable is returned. But void means that nothing is returned. This is a small but important difference. Therefor when return is even not called, void has to be declared in the function docblock.”

    Your theory works fine if you are the only person coding the application, but when you have 50 people working on the same project, it will be hard to assume that the return keyword is not present when the @return tag is not present.

    Good article!

    Aziz

    • Hi Aziz,

      Thanks for commenting :-)

      Just because one framework’s CS suggests to use it, doesn’t mean it’s right (the same as most of the framework’s CS not completely following PSR-1 and PSR-2 etc, for which there are supporters and haters of those too). http://pear.php.net/pepr/pepr-proposal-show.php?id=580 is a proposal to change the PEAR coding standard to make @return tags optional, for instance.

      I’m all for removing ambiguity, but not at the expense of extra maintenance and an inconsistency with the similar @global and @param tags.

      > Your theory works fine if you are the only person coding the application, but when you have 50 people working on the same project, it will be hard to assume that the return keyword is not present when the @return tag is not present.

      There’s no need to “assume” anything. Your company has a sniffer, phpDocumentor2 can easily identify when a return keyword is present with a corresponding @return tag, and checks like these, when there’s 50 people working on the code, can easily be built into Jenkins or pre-commit hooks. Let’s not bulk up and dirty the code with documentation QA checks that should be well outside of the production code.

  3. Hey Gary,

    We have a policy of following Zend documentation standards to the letter, this means we don’t have the luxury to dismiss any ZF possible coding conventions.

    I can see where you are coming form – as some of my colleagues also share the same opinion. I just do not see any negative side to adding more comments and can’t see how it makes the code bulky or dirty, if anything, it makes it much more elaborate and easier to understand for new developers.

  4. Aziz,

    > We have a policy of following Zend documentation standards to the letter

    That’s fine – that’s a company decision that’s been made and has likely been followed for a while. My article is for individuals or those who aren’t forced by someone else to do things a certain way.

    > I just do not see any negative side to adding more comments

    Inconsistency, maintenance, cluttering of all the other documentation

    > easier to understand for new developers

    “Hey look, there’s a @return tag, the function must be returning something. Oh…wait…it’s returning something called a void…I don’t know what that is, so let me check the actual code. Hmmm, I can’t find a “return” call anywhere in this function…”

    as opposed to

    “…”
    (because there’s no @return tag, because there’s no return keyword, so there’s nothing to document here.)

    • What you said makes sense. However, you can argue the same case for those who use sniffers, when someone is doing a “return;” in their code but no return docblock in the comments.

  5. I’m still trying to figure out all this @ tagging in comments… but something that I would like to understand (maybe I missed it in your article) is what to do in place of the `@return void` tag. Can I just delete it and be good?

    • Absolutely – this article puts my view forward that if there’s no return keyword in the function, there’s no need for a @return tag in the documentation, just the same as with a parameter (no parameter? no @param tag.). Others, as seen in the comments, like the belt and braces approach, and give a @return tag at all times – which apart from causing extra maintenance and redundant bytes, implies that the quality of the documentation is untrustworthy if a @return tag is missing.

Speak Your Mind

*