Phpdocs on local array

Question

My code review was refused by my co-worker, because of an unnecessary phpdoc on a local array ($params in bottom example) in a function. See the example:

/**
 * comment...
 *
 * @return int
 */
public function testFunction()
{
    /** @var string[] $params */
    $params = ['string1', 'string2'];

    etc...

    return 0;
}

Can someone explain to me why defining phpdocs on local arrays is unnecessary? I got an explanation from my co-worker that we don't need to write phpdocs on local arrays. We are using PhpStorm and Doctrine.

Thanks for your time.

Answer 1

Writing a phpdoc like string[] for an array is useful when the array is a parameter or a return value, so you can specify what types of values the array should contain. But in that case it's an array of string literals defined right there. The phpdoc isn't telling you anything you can't know just by looking at it.

Technically @var is intended to document class properties, but in some cases it can be useful inside a function to help the IDE when it's unable to determine the type of a variable. That's not really needed here either, though.

I can't know for sure if that's exactly why your co-worker thought it was unnecessary, but I don't see another logical explanation for it.