#Article #Типизация

Я уже ранее публиковал заметку про любопытное отличие Promoted Properties от обычных свойств в кишках #PHP.

Promoted Properties от того и Promoted, что очень неплохо продвигались в плане маркетинга.

Например, вот такая портянка:

class CustomerDTO
{
    public string $name;

    public string $email;

    public DateTimeImmutable $birth_date;

    public function __construct(
        string $name, 
        string $email, 
        DateTimeImmutable $birth_date
    ) {
        $this->name = $name;
        $this->email = $email;
        $this->birth_date = $birth_date;
    }
}

превращается в такую:

class CustomerDTO
{
    public function __construct(
        public string $name, 
        public string $email, 
        public DateTimeImmutable $birth_date,
    ) {}
}

Вау! Круто!
Но не раскрыта тема комментариев.
Если вы не пишете комментарии в коде, то вам, в прочем, без разницы 😑 но мне вот приходится 😫

Как правило, если требуется указать более точный "псалмовый" тип, то он перемещается из аннотации @var в аннотацию @param над конструктором, поэтому иногда получается такое говно, в котором нужный тебе параметр пойти найди.
А т.к. я обычно пишу непонятные тулзы, которые хер пойми как работают, то в комментариях часто нужен не только текст, но и вставки кода, дополнительные аннотации типа @internal, @note, @since, @see, @link.

И хорошего решения тут нет.

👉 Писать портянку под @property — тем всратее, чем больше комментариев и параметров.

👉 Писать типы и комментарии непосредственно над параметром — всрато.

class CustomerDTO
{
    public function __construct(
      /**
       * @var non-empty-string Comment here
       * Example here
       */
        public readonly string $name,
    //...
    ) {}
}

👉 Не использовать Promoted Properties и дублировать комментарий — всрато, но есть исключения (если свойство публичное, а конструктор internal, то в конструкторе можно обойтись только типом).
И даже если сделаешь красиво, то всё-равно потом придёт какой-нибудь умник с ректором или CS фиксером и запромоутит разом все параметры 🚽