Всегда приятно читать хорошо оформленный и документированный код. Его не только в разы проще читать и понимать, но и на него просто приятно смотреть. Как правило, начинающие программисты леняться документировать свой код в силу тех или иных причин. Сам раньше не документировал. Но после того как пришлось разбираться в чужом сложном и не документированном коде понял, что не документировать код - это страшный эгоизм и издевательство над своими коллегами. Вот будет кто - то читать мой код, когда я с ним уже закончу, и будет громко произносить в мой адрес страшные эпитеты. Поэтому теперь я стараюсь документировать свой код как можно тщательнее. Тем более, что не задокументировав код и вернувшись к нему через некоторое время, опять придется в нем разбираться, потому что уже все забыл.
Одной из преград к документированию кода для меня было то, что я не знал как это правильно делать. Но тут меня выручил замечательный стандарт 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 Комментариев