PHPDoc file headers

[szepeviktor]

Would you welcome valid File-level DocBlocks?

/**
 * @package           Fidry\Console
 * @author            Théo FIDRY <theo.fidry@gmail.com>
 * @copyright         2022 Théo FIDRY
 * @license           https://github.com/theofidry/console/blob/main/LICENSE MIT
 */

[theofidry]

Hi,

I would prefer not (unless there is real value) as they genuinely are not that relevant, the information is redundant with others, it's a bit annoying to keep in sync and I do not have them for any of my other projects either.

Thanks for proposing though :)

[szepeviktor]

(unless there is real value)

I like following standards and keep my inventions out of the computer. e.g. https://github.com/szepeviktor/phpcs-psr-12-neutron-hybrid-ruleset/blob/190dec139b8c507f41bfe1bcb41359cea7f8a6fe/PSR12NeutronRuleset/Sniffs/Strings/ConcatenationUsageSniff.php#L3-L7

[theofidry]

I'm having a bit of trouble to follow.

• What value provides @package? On its own it may at best indicate the top level namespace (in which case it is redundant with the namespace declaration) but otherwise it is not even referring to the Composer package name (which can be different than the namespace name). To me, it comes off as an artifact from old PHP versions before PHP namespaces were introduced.
• I do like the @author when the file is created/edited by someone else, but the license is already mentioned. Symfony makes usage of it a lot for example
• copyright & license are already included as header files. Maybe it could be replaced in favour of this PHP annotations but at least in my case I've been using so much the previous ones, I don't think it's worth switching to something else

[szepeviktor]

What value

Sorry. I'm not a businessman. I do things the best way I can in my laboratory.

It is possible that following phpDocumentor has no measurable value in this case. I think docblocks are nice and I'm happy when I see them on my screen :)

[theofidry]

Oh I did not mean monetary value :) (I am no business man myself!). However like everything, changing things has a cost in time & efforts and they are always limited resources, hence trying to figure out if there is a real benefit from it.

It is possible that following phpDocumentor has no measurable value in this case.

Ha it's been a very long time since I last checked/used phpDocumentor I admit! It might be a different story for some specific files, but I otherwise would expect those information to be picked from the composer.json in general (i.e. the default comes from there, then maybe a specific file might override some of this information differently). If it's not then I think it's missing out on that feature, because I don't think there is many people using all of those tags consistently in the PHP ecosystem.

I'm almost 50 years old. Maybe an old man is used to his ways :(

Don't worry, I'm more in the middle but even youngsters can pick up habits very quickly ;)