Зачем (в наше время) везде писать phpdoc комменты?

Уже вторая контора, где требуют всюду писать phpdoc комменты, причем по факту это какая-то бесполезная писанина за авторством К.О.:

/**
 * Class FloatToStringConverter
 *
 * Converts float value to string with specific precision
 */
class FloatToStringConverter
{
    /**
     * Default precision
     */
    private const DEFAULT_PRECISION = 2;

    /**
     * @var int
     */
    private int $precision;

    /**
     * FloatToStringConverter constructor.
     *
     * @param int $precision
     */
    public function __construct(int $precision = self::DEFAULT_PRECISION)
    {
        $this->precision = $precision;
    }

    /**
     * @param float $value
     * @return string
     */
    public function convert(float $value): string
    {
        return (string)round($value, $this->precision);
    }
}


Какая информация потеряется, если убрать phpdoc? Никакой. При этом на написание комментариев нужно время, а еще они создают визуальный шум и затрудняют чтение кода.

Вопрос: зачем использовать комментарии везде, если код самодокументируемый, и они нужны только в исключительных случаях, когда не хватает возможностей языка - типа тайп хинт float|int, коллекции/массивы string[], Type[]?

В 2 раза легче же читается:

class FloatToStringConverter
{
    private const DEFAULT_PRECISION = 2;
    
    private int $precision;
    
    public function __construct(int $precision = self::DEFAULT_PRECISION)
    {
        $this->precision = $precision;
    }
    
    public function convert(float $value): string
    {
        return (string)round($value, $this->precision);
    }
}
  • Вопрос задан
  • 705 просмотров
Решения вопроса 1
@EvgeniiR
https://github.com/EvgeniiR
Посторонним В.,
Мой вопрос не про комментарии в клиентском коде, а именно про пхп-док блоки для классов и их членов, т.к. они почему-то часто считаются стандартом де-факто.

Дублирование типов в php-доках не нужно и никаким стандартом не является(если только внутренним-корпоративным).

P.S. И да, если бы программисты хоть иногда, перед тем как что-то заюзать задавали себе вопрос, зачем они это делают, и нет ли способов делать дела лучше, индустрия разработки была-бы совсем другой.
Ответ написан
Пригласить эксперта
Ответы на вопрос 6
Kozack
@Kozack
Thinking about a11y
  • Не всегда то, что сейчас кажется самодокументированным кодом будет восприниматься так же спустя время.
  • Каким бы ни был хороший код, простое предложение с описанием для каких целей нужно это свойство, проще для восприятия, чем искать его по всему классу.
  • Это нужно для генерации документации. В которой будут не только названия свойств и методов, но и их описания. На русском, если нужно.
  • Если в проект приходит новичок, ему проще вникнуть имея документацию.
  • Некоторые IDE могут показывать подсказки с комментариями и доп инфой из phpdoc


Как ты ни крути, документирование это крайне важно. Возможно, требовать комментировать вообще всё, с точки зрения компании, немного излишне. Но это может помочь в дальнейшем рефакторинге когда код немного выйдет из под контроля. Это такое ограничение, которое доставляет неудобства программисту, но сдерживает его от выстрела в ногу.

Но, это всё справедливо в случаях, когда комментарии представляют собой чуть больше чем
/**
 * @var int
 */
private int $precision;
Ответ написан
Adamos
@Adamos
Если вы пишете исключительно классы-конверторы из числа в строку, документировать их, действительно, незачем.
В нормальной же работе многие классы представляют собой переходник между уровнями логики, где метод - это оператор более высокого уровня, а его содержимое относится к более низкому. Так что даже прочитав текст метода, можно будет понять, что он делает, но не понять - зачем и к какому разделу бизнес-логики это действие вообще относится. А тут - комментарий первой же строчкой! От кодера, которому вдолбили в башку, что комментировать надо все, и только поэтому он не поленился сделать это и здесь тоже.
Ответ написан
@Arik
Есть интересные товарищи: __call(), __get() и __set() которые дают интересную магию и головную боль без php-doc
Ответ написан
@Devi2005
Не помню где прочитал фразу, но она мне понравилась. "Комментарии, это извинения программиста за нечитаемый код." Документирование каких-либо сложных решений нужно, но не всего же подряд.
Ответ написан
index0h
@index0h
PHP, Golang. https://github.com/index0h
Если сгенерированная дока по коду публикуется, в этом может быть смысл
Ответ написан
profesor08
@profesor08 Куратор тега PHP
Чтоб навести курсор на метод и прочитать, что он там делает и за что отвечают его параметры. Ну, а в большинстве случаев это просто стандарт кода, либо соблюдаешь, либо не работаешь.
Ответ написан
Комментировать
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы