Twin//Slash © 2010

Использование комментариев phpDocumentor

   

Важность документации

”Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.”

Dick Brandon

   

phpDocumentor

Комментарии – важная часть кода

Комментарии должны быть:

полными

точными

своевременными

   

phpDocumentor

Он же PHPDoc

http://www.phpdoc.org/

   

Комментарии

Комментарии PHPDoc пишутся в специально отведенных для них местах с помощью специальной разметки.

Могут быть сконвертированы в HTML, PDF или CHM файлы 

$ phpdoc ­h

   

Комментарии

Комментарии PHPDoc всегда многострочные и выглядят следующим образом

/**

 * Комментарий

 */

Как правило, все современные IDE автоматически поддерживают и дополняют такой блок комментариев.

   

Комментарии

HTML или wiki разметка внутри текста комментариев

/**

 * Внутри функции

 * * создаем переменную

 * * уничтожаем переменную

 */

   

Комметария

Комментариями PHPDoc сопровождается

каждый файл

каждый класс

каждое свойство или константа класса

каждый метод класса

каждая функция

   

Теги

@<тег> <информация тега если есть>

/**

 * @param string $name Имя пользователя

 */

   

Основные теги

@author Автор с указанием e­mail

/**

 * @author Aliaksei Shytkin <e79eas@gmail.com>

 * @author Mahatma Harash <krishna@gmail.ind>

 */ 

   

Основные теги

@version $Id$

Версия с автоматическим подставлением информации о последней ревизии файла

   

Основные теги

@package <имя пакета>

@subpackage <имя подпакета>

Для указания структуры проекта

/**

 * @package Form

 */

   

Основные теги

@var <тип переменной> <описание>

Для свойств классов

Тип переменной используется IDE для автокомплита

/**

 * @var sfGuardUser Владелец экземпляра класса

 */

$owner = null;

   

Основные теги

@param <тип переменной> имя <описание>

Для функций и методов

Тип переменной используется IDE для автокомплита

/**

 * @param sfGuardUser $user Пользователь оплачивающий ордер

 * @param mixed $order Данные ордера 

 */

public function process($user, $order){}

   

Основные теги

@return <тип переменной>

Для фукций и методов

/**

 * @return sfGuardUser 

 */

public function getOwner()

{

  return $this­>owner;

}

   

Основные теги

@todo <указание как в будущем изменить код>

/**

 * @todo Перенести в шаблоны 

 */

public function translateTitle()

{

  return __($this­>title);

}

   

Пример

Живой пример написания кода с комментариями

   

Другие комментарии

Имеет смысл оставлять важные комментарии внутри блоков кода, если они необходимы.

Комментарии ставятся на строке перед комментируемым блоком кода. В данном случае все комментарии однострочные с пробелом после знака комментария

   

Другие комментарии

// проверка на действительность 

// пользователя

if ($user­>is_active && $user­>registered_at == '01­01­2001')

{

}

   

symfonyКомментарии

В фреймворке symfony комментарии необходимы

для каждого из подключаемого плагина в файле ProjectConfiguration.class.php

для каждой инструкции внутри файла ProjectConfiguration.class.php

для каждой связи события $this dispatcher connect→ →  в файле конфигурации приложения

   

YAMLКомментарии

Опыт показывает необходимость комментирования YAML­файлов

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

к каждому полю модели в yaml файле модели и другим инструкциям внутри файла модели

   

YAMLКомментирование

# таблица для хранения заявок

Tender:

  columns:

    # имя

    name:

      type: string(255)

   # описание

   description:

    type: clob

   

Спасибо за внимание

Вопросы?