Are docblock typehints redundant when using strict typing

Question

I have a quite large private codebase which has evolved for about ten years now. I'm not using phpDocumentor but since using docblock sections has become quite the standard in open source projects I have adopted writing docblocks for all public methods in my repository as well. Most blocks just contain a small description and typehints for all parameters and the return type.

With the arrival of static analysis, these typehints have helped me a lot finding inconsistencies and possible bugs. Lately I've converted the entire codebase (Now running on PHP7.2) to have all parameters and return values type-hinted where possible, using PHP's typehints. And now I am wondering... Aren't these docblock typehints redundant? It asks quite a bit of work to keep all docblocks in sync with the ever changing code and since they don't add any new information I am wondering whether it is better to completely remove them or not.

In one hand, removing documentation feels bad, even when it is redundant. In the other, I really feel like breaking the Do-Not-Repeat-Yourself-principle everyday type-hinting stuff that is already type-hinted.

Answer 1

Information that can be found in the code should not be duplicated in comments.

At best, it's wasted effort to keep them synchronized. More likely, they will get out of sync eventually. At that point, they are just confusing.

If you look at the DocBlock equivalent in statically typed languages (e.g. Java, C#), you will find that doc comments do not contain type information. Insofar as this is the case in your PHP code, I'd strongly advise to follow suit. Of course, where type hinting cannot be applied, a comment is still your best alternative.

This is not relevant to PHP, but duplicated type information can make sense when the type is implicitly inferred (e.g. Haskell).

Answer 2

Yes, docblocks have become redundant with php 7.

Most time in coding is spent reading, so having to read the same thing twice impacts your productivity. Furthermore, it makes it easy to miss actually important comments.

I don't write docblocks anymore, except when I want to type hint an array of a certain type (e.g. @return int[] or @param SomeStatus[] $statusList) or when I want to add a comment about the method, parameters or return value. I found it important to disable the phpstorm inspection that triggers when you don't have alle parameters and return types in a docblock if you have a docblock.

Answer 3

The code and the documentation typically have different audiences: documentation is for users of that function. They shouldn't have to look at the code to understand the types. Therefore, the documentation should include all necessary information, including types.

In some systems, it is not necessary to specify a parameter type in the documentation because the type can be taken from the code. PHPDoc is not such a system. Instead, the @param tag is documented that

When provided it MUST contain a Type to indicate what is expected

The “quite a bit of work to keep all docblocks in sync with the ever changing code” is somewhat reduced because PHPDoc will check the documentation type hints against the code type hints. This is a kind of linting/static analysis, so make your documentation generation a part of your automated test pipeline.

Another question you might want to ask yourself is why these functions are documented in this detail when they are “ever changing”. The usual motivation is to create a HTML reference manual of your interfaces. But if the documentation is never read outside of an IDE, or if you don't have stable interfaces where documentation makes sense, then detailed docblocks are unnecessary or even misleading. It can be better to only write a summary, and defer full docs until you have arrived at a stable design.