From In-Portal Developers Guide

Revision as of 12:42, 6 September 2008

Стандарты в программировании
Статьи в этой категории
Форматирование PHP файлов Назначение имён Стиль программирования Правила хорошего тона Сопутствующая документация

Формат документации

Все блоки с документацией должны быть совместимыми с форматом, используемом в phpDocumentor. Описание phpDocumentor формата не является целью этой статьи. За более подробной информацией посетите http://phpdoc.org/. Во всех файлах, в которых находиться PHP код самого K4 или код его использующий, сверху должен находиться "file-level" блок документации. Над каждым классом следует писать "class-level" блок документации. Ниже приведены примеры подобных блоков.

Файлы

Каждый файл в котором находиться PHP код должен вверху содержать блок документации состоящий как минимум из ниже приведённых тэгов формата phpDocumentor:

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * @copyright  2008 Intechnic Corporation
 * @license    http://www.intechnic.com/license.txt
 * @version    $Id:$
*/

Классы

Каждый класс должен вверху содержать блок документации состоящий как минимум из ниже приведённых тэгов формата phpDocumentor:

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @copyright  2008 Intechnic Corporation
 * @license    http://www.intechnic.com/license.txt
 */

Функции

Каждая функция, включая методы объектов должна сопровождаться блоком документации со следующим содержанием:

• описание;
• список всех аргументов;
• все возможные возвращаемые значения;

/**
 * Short description
 * 
 * Long description
 *
 * @param kEvent $event
 * @param int $mode can accept values hBEFORE or hAFTER
 * @return Array
 */

В приведённом выше примере показано, как можно описывать аргументы функций (тип значения, название, описание), а также её описание и тип возвращаемого значения. Если функция является событием в обработчике событий то:

• если событие это hook, то нужно написать "[HOOK] " перед его кратким описанием;
• если событие вызывается в результате AJAX запроса, то нужно написать "[AJAX] " перед его кратким описанием.

Такие краткие дополнения к описанию события помогут понять где его применяют, если из названия события это не становиться ясным.

В случае, когда используются ключевые слова "public", "private", или "protected" указывать "@access" в блоке документации не обязательно.