#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 фиксером и запромоутит разом все параметры 🚽

#Article

Кстати, а вставки кода в комментариях — тоже кучерявая тема в #PHP.

👉 Есть Java-like вариант: оборачивать тегами <code>. Скуфы, мб, помнят.
Но мы, вроде, уже ушли от HTML среди PHP 😏

class CustomerDTO
{
    /**
     * @var non-empty-string Comment here
     * 
     * <code>
     * $x = foo()->bar();
     * </code>
     */
    public readonly string $name;
}

👉 Есть Python-like вариант: делать отступы

class CustomerDTO
{
    /**
     * @var non-empty-string Comment here
     * 
     *     $x = foo()->bar();
     */
    public readonly string $name;
}

Тут не очень очевидно, сколько пробелов от звёздочки должно быть: по логике 1+4, но не сходится с разметкой Tab-ов.
Это активно используется в Symfony и PhpStorm это даже рендерит. Кстати, кто знает, как отключить этот рендеринг для классов из vendor?

👉 Есть Markdown-like вариант:

class CustomerDTO
{
    /**
     * @var non-empty-string Comment here
     * 
     * ```php
     * $x = foo()->bar();
     * ```
     */
     public readonly string $name;
}

Мне нравится markdown, но это не рендерится PhpStorm'ом. Однако, рендерится документором.
Python-like на документоре не проверял, может тоже рендерит.