Когда нужно писать phpdoc?

Question

[felony13twelve]

Здравствуйте! Задался таким вопрос, когда нужно писать phpdoc комментарии? Врятле же их нужно писать в каждом методе. Допустим у меня есть класс View.php нужно ли в нём писать эти комментарии?

Comments

[Дмитрий]

Лучше писать, а можно просто использовать нормальную ide
Она их автоматом заполнит после **/ и энтер

[Дмитрий]

Дмитрий, может /** enter? Доверяй, но проверяй, иногда ide не всегда корректные данные пишет.

[Дмитрий]

Дмитрий, ну если в строгой типизации писать, то на 90 процентов все сходится, в любом случае проще чуть исправить, чем полностью пилить

Answer 1

[Сергей delphinpro]

Для начала нужно понять, что это не комментарии, а документация, встроенная в код.

Если вы собираетесь генерировать потом документациию по phpdoc, то однозначно нужно описывать каждый метод и каждое поле, а также функции и константы.

Кроме того, phpdoc используются продвинутыми IDE для автозавершения кода.
Если вам phpdoc нужны только для автозавершения, то тут нужно учесть, что современный php уже и так позволяет указывать типы параметров и возвращаемых значений. Подобные блоки комментариев чаще всего будут излишними. Однако не всегда используется строгая типизация. Особенно в возвращаемых значениях.
В этом случае полезно бывает указать несколько возвращаемых типов в doc-блоке, чтобы IDE смогла подсказывать все имеющиеся методы возвращенного объекта.

Итого: для ведения документации описываем всё, для автозавершения в IDE пишем выборочно. Остальное по вашему желанию или по требованию работодателя/руководителя проекта.