Немного о документировании кода. Стандарт Docblock.

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

Одной из преград к документированию кода для меня было то, что я не знал как это правильно делать. Но тут меня выручил замечательный стандарт 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:

dockblock netbeans

Жизнь существенно упрощается, не только для вас, но и для ваших коллег! Не будьте эгоистом.

Это конечно только капля в море, но я думаю вы уловили основную суть.

Ссылки по теме:

  • https://bit.ly/aDlWlq
  • https://bit.ly/c7vAEO
Тэги :

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

    Элементы 1—1 из 1.
    • Олег
      В наше время, на php очень много быдлокодеров, которые позорят этот язык программирования. В php много свободы. Если сравнивать предположим с C++, либо C#, то в PHP просто раздолье для творчества. Конечно, лучше заранее предопределять переменные и так далее, но для новичков это нудно наверное. Зато, потом открыв код, там мало чего понятного. Я читаю о PHP на портале проекта Web Decode, там можно найти много чего полезного, как для новичков, так и для профессионалов.

Оставьте комментарий

Мы не опубликуем ваш email

Scroll To Top