Search code examples
phpcomments

Are comments invoking code a language feature or antipattern?

I stumbled upon some Nette code where comments were used to set class attribute, and the Nette doc approves it:

class Foo {
  /** @var someClass @inject */
  public $bar;
}

Having PHP Reflection at hand, should I use coments invoking code more as a standard language feature ("comments based coding"), or should I avoid it as an antipattern? Are there any authoritative resources advocating or denouncing such comments handling?

Solution

  • PHP did not support annotations until recently. PHP 8 introduced attributes. It was released in end of November 2020. As of now attributes are not widely supported.

    The pseudo-annotations from your example are the current best practice used by most major frameworks and libraries like Doctrine ORM. The latter even provides a doctrine/annotations-library which makes using these user land-annotations more convenient.

    As for an authoritative source for whether this is a good practice, it is explicitly mentioned in the RFC for the language feature: https://wiki.php.net/rfc/attributes_v2#userland_use-casemigrating_doctrine_annotations_from_docblocks_to_attributes (the syntax in the RFC looks different than the actual attribute syntax as it was changed).