Бессмысленные докблоки считаются вредными

Докблоки (в переводе PHP), также известные как Javadoc или комментарии к документам в мире Java, рассматриваются как один из немногих типов допустимых комментариев, которые можно вставить в код. Этот стиль — рефакторинг кода, чтобы показать его намерение, а не просто вставку комментариев — принимает docblocks как необходимое зло.

Тем не менее, docblocks может стать таким же злом , как комментарии , когда они не рассматриваются как граждане первого класса . В примерах, приведенных в этой статье, показан код PHP, но рассуждения в целом не верны для любого языка, на котором написаны docblocks на уровне методов.

Слишком часто докблоки генерируются и остаются там без какой-либо дополнительной информации. В других случаях они заполняются механически информацией, которая уже может быть выведена. В этом случае вы не помогаете программистам, которые должны будут поддерживать этот докблок, содержащий информацию, дублированную из сигнатуры метода.

Написание хорошего докблока занимает несколько секунд и некоторые рассуждения, и вот несколько практических правил о том, как я пытаюсь написать свой. Чем больше вы прилагаете усилия, чтобы записать их в качестве ценной информации, тем меньше трудностей для их обслуживания и для коллег, читающих ваш код.

Первый принцип

Основная директива в написании доклоков — не говорите то, что уже известно . Если вы собираетесь вставлять только пустые аннотации @param и повторять имя метода, лучше без докоблока: инструмент синтаксического анализа, будь то Javadoc или PHPDocumentor, уже сможет вывести из сигнатуры метода, что Вы хотели повторить.

Второй принцип

И второй принцип … не говорите то, что уже известно. В самом деле. Если бы бессмысленные docblocks состояли из кода , мы были бы беспощадны и уничтожили бы их как код, который не нужен для прохождения тестов (или для выполнения задачи в приложении, если вы предпочитаете это определение).

В методе с именем makeSnafucated вставьте только JavaDoc / * make snafucated * / . Никогда не определить , что snafucated средства в любом месте . Только дурак не знает, с полной уверенностью, что значит » раздутый» . Для классических примеров этой техники обратитесь к Sun AWT JavaDOC. — Как написать не поддерживаемый код

Вот вместо этого значимый докблок.

/**
 * Extracts the square root of $value, that is, the $result such that
 * $result * $result == $value.
 * @param float $value  must be positive
 * @return float        will always be positive by definition
 * @throws InvalidArgumentException if $value is less than 0 or not numerical
 */
public function sqrt($value) { ... }

Давайте посмотрим, почему такой докблок был бы полезен.

• описание метод отличается от имени метода ; так как он будет прочитан кем-то, кто пытается вызвать ваш метод (кто уже знает имя метода), он предоставляет информацию, которой нет. Вы будете удивлены тем, сколько докоблоков я встречаю, которые просто повторяют название метода на естественном языке (обычно на английском). Это не просто, но задача состоит в том, чтобы последовательно применять этот принцип. Полные проекты с открытым исходным кодом (например, Doctrine 1) содержат сгенерированные docblocks, которые ничего не говорят .
• описание не содержит никаких деталей реализации , однако: в случае математической функции, алгоритм , используемый для расчета скрыто (если это не важно ради производительности.) Все мы знаем, этот метод можно использовать PHP примитивной функцию SQRT (), или приближение, основанное на усеченном ряду.
• параметры устанавливают свои предпосылки . Не ожидайте, что вы сможете вызвать $ object-> sqrt (-1).
• в описании результата указывается условие post, которое будет удовлетворяться методом всякий раз, когда он не вызывает исключение. В этом случае, даже если (-2) * (-2) равно 4, sqrt (4) будет следовать определению и будет рассчитано как 2.
• цитируются случайные исключения с указанием их типа и причины, по которой они будут выброшены.