PHP

Документируем код при помощи PHPDoc

Почему же так плохо обстоят дела с документированием кода в PHP?

php-html-code

Хорошо написанный код можно не комментировать, документация ему не нужна

Senior Joomla  Developer

Как бы не грустно было это говорить, но такие куски кода встречаются чаще, чем хотелось бы:

  • метод getObjects() никак не описан,
  • что попадает в $object — не понятно
  • во всем проекте найдется 100500 классов, имеющих doSomething()

С подобным можно очень эффективно справиться применяя phpdoc. Подводные камни в том, что phpdoc:

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

Ввиду этого разработчики зачастую игнорируют документирование своего кода. А зря.

В проектах, которые предусматривают поддержку, документированный код позволит сохранить большое количество время. Кроме того, достаточно будет использовать всего лишь несколько тегов. Давайте их рассмотрим.


Константы внутри классов:


 Свойства классов:


Методы:


Описания классов (и т.д.):


Переменные:


Возможности phpdoc намного шире. Можно документировать: функции, константы, классы, интерфейсы, трейты, константы классов, свойства, методы. В описания можно добавить горы информации…

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

Поделитесь с друзьями или сохраните себе
  •  
  •  
  •  
  •  
  •  
  •  
  •  

Напишите комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *


одиннадцать + 10 =