Всегда приятно читать хорошо оформленный и документированный код. Его не только в разы проще читать и понимать, но и на него просто приятно смотреть. Как правило, начинающие программисты леняться документировать свой код в силу тех или иных причин. Сам раньше не документировал. Но после того как пришлось разбираться в чужом сложном и не документированном коде понял, что не документировать код - это страшный эгоизм и издевательство над своими коллегами. Вот будет кто - то читать мой код, когда я с ним уже закончу, и будет громко произносить в мой адрес страшные эпитеты. Поэтому теперь я стараюсь документировать свой код как можно тщательнее. Тем более, что не задокументировав код и вернувшись к нему через некоторое время, опять придется в нем разбираться, потому что уже все забыл.
Одной из преград к документированию кода для меня было то, что я не знал как это правильно делать. Но тут меня выручил замечательный стандарт Docblock. В нем описывается как надо правильно писать комментарии к коду, чтобы он был не только легко читаем человеком, но и понимался различными IDE для формирования всплывающих подсказок.
Итак, начнем. Каждый файл кода несет в себе смыловую нагрузку. Поэтому а начале каждого файла надо дать его краткое описание.
<?php /** * Короткое описание файла * * Подробное описание файла (если есть) * * PHP версии 5 * * * @category Название категории * @package Название пакета * @author Автор оригинала <author@example.com> * @author Автор правок <another@example.com> * @copyright Ваш копирайт * @license Ссылка на текст лицензии * @version Версия * @link Ссылка на документ или элемент * @see Тоже ссылки. Аналог в литературе: "(см. рис. 1)" * @since Когда файл появился в библиотеке * @deprecated Начиная с какой версии файл устарел */
Читая данный код, сразу становиться понятно что это за файл и что он описывает. Комментарии docblock начинаются с сочетания символов /** и на каждой новой строчке идет символ *. Заканчивается как обычный многострочный комментарий символами */
Идем дальше, посмотрим еще код.
/**
* Это простой docblock комментарий.
* В данном случае тут можно написать зачем нам нужен данный require_once
*/
require_once 'PEAR.php';
/**
* Описываем значение константы
*/
define('NET_SAMPLE_OK', 1);
/**
* Описываем значение глобальной переменной
* @global int $GLOBALS['_NET_SAMPLE_Count']
*/
$GLOBALS['_NET_SAMPLE_Count'] = 0;
Итак, впереди самое вкусное - комментирование классов и переменных.
<?php
/**
* Название класса. Одна строчка.
*
* Подробное описание класса. Можете написать сколько угодно строчек.
* Это не обязательная часть, но часто очень желательная.
*
* Вы также можете добавить тэги. Они пишутся так: @tag. tag - название тэга.
* Каждый тэг несет какую-то смысловую нагрузку.
*
* @author Jason Lengstorf <jason.lengstorf@ennuidesign.com> - имя автора
* @copyright 2010 Ennui Design
* @license https://www.php.net/license/3_01.txt PHP License 3.01
*/
class SimpleClass
{
/**
* Краткое описание переменной
*
* После тэга @var идет тип переменной и значение.
*
* @var string хранит данные класса.
*/
public $foo;
/**
* Краткое описание функции
*
* При описании функции надо описать входные и выходные параметры.
*
* @param string $val a value required for the class
* @return void
*/
public function __construct($val)
{
$this->foo = $val;
}
/**
* Перемножение двух значений
*
* Принимает пару двух значений и вычисляет их произведение.
*
* @param int $bat Первый аргумент
* @param int $baz Второй аргумент
* @return int Результат перемножения
*/
public function bar($bat, $baz)
{
return $bat * $baz;
}
}
?>
Как видите, код стал сразу красивым и читабельным. Но это еще не все прелести. Одной из главных особенностей является то, что почти все современные IDE понимают стандарт docblock и могут выдавать подсказки по ним. Например в NetBeans:
Жизнь существенно упрощается, не только для вас, но и для ваших коллег! Не будьте эгоистом.
Это конечно только капля в море, но я думаю вы уловили основную суть.
Ссылки по теме:
- https://bit.ly/aDlWlq
- https://bit.ly/c7vAEO
1 Комментариев