Как обеспечить документированность кода

Вступление

Практически каждый PHP-разработчик добавляет в свой основной код комментарии. Но сам язык не определяет жесткими правилами, как это делать. Вы просто должны включить в код некоторые специальные теги, и между ними вы можете написать любую информацию, которую сочтете нужным.

Так что же следует помещать в блоки комментариев, чтобы они были полезны? Какие части кода должны быть задокументированы, а какие нет?

В этой статье я представлю несколько важных правил, которые помогут вам в том, чтобы ваши PHP-коды были хорошо задокументированы и понятны.

1. Пишите код, который поясняет сам себя

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

Вот лишь несколько примеров:

Названия переменных, функций, классов

То, что практически всегда вы можете называть свои фрагменты кода так, как вам нужно, вы можете использовать для того, что поддерживать читаемость кода.

Только не забудьте, что нужно выбирать очень понятные названия, никаких странных аббревиатур или названий, которые могут быть истолкованы неоднозначно. Если переменная представляет собой экземпляр класса VeryImportantCustomer, просто назовите ее $veryImportantCustomer, а не $customer, $vimpCust или $tempcustomer.

Не бойтесь опечаток в длинных названиях, ваш IDE, вероятнее всего, предупредит вас о неиспользованных переменных или других несоответствиях в коде. Я уверен, что с помощью правильных названий, вам будет потом намного проще разбираться с различными блоками вашего кода.

Это простое правило, но многие легко забывают о нем в своей повседневной работе.

Метки типов

PHP позволяет разместить названия классов /интерфейсов или ключевые слова array /callable рядом с параметрами функции.

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

И помните, что ваш IDE-движок, также может интерпретировать метки типов и использовать их для вывода всплывающих окон с описаниями функций, которые в данный момент отображаются в вашем рабочем файле.

Метод видимости

Другой подход, о котором стоит упомянуть, это метод видимости. Назначение соответствующей видимости методам классов является важной частью создания качественного объектно-ориентированного кода.

С одной стороны, с помощью данного метода можно указать, какой код представляет ту часть логики, которая должна остаться внутри класса и не должна взаимодействовать к другим классами приложения.

С другой стороны, он предоставляет определенные методы классов для общего доступа, и они могут быть вызваны из-за пределов класса и взаимодействовать с другими частями приложения.

Если вы пишите код, включающий установки соответствующего метода видимости, другие разработчики быстро смогут определить, как работать с классом, который вы создали. Они найдут несколько открытых методов, которые помогут им сориентироваться в коде.

Они также смогут видеть, какие части прописанной вами логики должны обрабатываться только частными методами классов, и, соответственно, их не стоит трогать.

Опять же, такие метки интерпретируются вашим IDE. Редактор, который вы используете, вероятно, сможет показать вам список методов классов, а также их видимость.

Посмотрите на изображение, приведенное ниже, и обратите внимание на значки замка рядом с названиями методов:

2. Сохраняйте баланс

Конечно, вы можете почувствовать, что самого кода не всегда достаточно, чтобы четко понимать логику, и к нему нужны дополнительные пояснения.

Особенно это касается случаев, когда вы реализуете сложную часть бизнес-логики, выполнение сложных вычислений или просто используете команды, которые трудно понять при беглом рассмотрении (такие как шаблоны регулярных выражений, массив преобразований и т.д.)

В таких случаях добавление кратких комментариев, безусловно, поможет другим людям понять, что делает код.

С другой стороны, блоки комментариев не должны восполнять недостатки плохо написанного кода. Если ваш код содержит слишком много циклов и управляющих конструкций, и даже вы не можете понять, что как работает, пока не проанализируете его, оставить код в таком состоянии, просто добавив несколько строк комментариев, не самое лучшее решение.

Вы должны приложить некоторые усилия, чтобы перестроить код, вместо того, чтобы пояснять запутанные места в комментариях.

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

Позвольте показать вам один пример:

<?php
    class Deposit {

        /**
         * Владелец депозита.
         *
         * @var string
         */
        private $_owner;

         /**
         * Сумма на депозите.
         *
         * @var float
         */
        private $_amount;

        /**
         * Дата открытия депозита.
         *
         * @var DateTime
         */
        private $_dateOpened;

        /**
         * Класс конструктора.
         *
         */
        public function __construct() {
            //...
        }

        /**
         * Установка владельца депозита.
         *
         * @param string $owner Имя владельца депозита.
         */
        public function setOwner($owner) {
            $this->_owner = $owner;
        }
?>

Помните, что человек, который читает ваш код, как правило, является разработчиком (или, по крайней мере, я полагаю, что он должен являться таковым), и он должен быть в состоянии сам понять, что параметр _owner класса Deposit представляет владельца депозита.

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

Также зачастую комментарии не нужны в других простых частях кода, не только в определениях свойств класса или стандартных методах (например, в таких как конструкторы, извлекатели или установщики).

Просто посмотрите пример, приведенный ниже:

<?php

public function showUserDetails() {
    $userId = $this->Session->read('userId');
    $userData = $this->getUserData($userId);
    if(!$user->isActive()) {
        throw new Exception("Аккаунт пользователя не может быть активирован.");
    }

    //...
}
?>

Я уверен, что вы можете сами легко понять, что делает фрагмент кода, представленный выше. Но если вы захотите прокомментировать код, то это, вероятно, будет выглядеть следующим образом:

<?php
/**
 * Вывод реквизитов текущего пользователя. 
 *
 */
public function showUserDetails() {
    //определение текущего пользователя на основе сессии
    $userId = $this->Session->read('userId');   

    //загрузка данных пользователя из базы данных
    $userData = $this->getUserData($userId);

    //проверка, имеет ли пользователь активный аккаунт
    if(!$user->isActive()) {
        throw new Exception("Аккаунт пользователя не может быть активирован.");
    }

    //...
}

?>

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

По моему мнению, метод, показанный в примере выше, не нуждается ни в каких дополнительных комментариях, поскольку все описывается самим кодом.

Конечно, я по-прежнему рекомендую вам писать комментарии в тех частях вашего приложения, которые являются более сложными и нуждаются в дополнительном пояснении.

3. Не забывайте о Doc-блоках

Как вы могли видеть в примерах кода, приведенных ранее, некоторые блоки комментариев содержат определенные ключевые слова, начинающиеся с символа @.

Я использовал @var, чтобы описать тип свойств класса, и @param, чтобы указать тип параметра метода. Вы также можете использовать тег @return, который указывает тип значения, возвращаемого функцией.

Другие теги могут быть использованы для описания некоторой общей информации о приложении или его части (таких как автор, пакет, тип лицензии). Теги Doc-блоков содержат информацию, которая не может быть включена в сам код.

Определение типа свойств класса или возвращаемых значений функций особенно полезно, поскольку оно может быть распознано большинством интегрированных сред разработки и выведено через подсказки.

Конечно, вы также можете вставить в Doc-блок собственный текст, который будет использоваться в качестве документации к функции или классу.

Это особенно важно, если ваш проект должен иметь дополнительную документацию, прилагаемую к коду. В таком случае вы можете использовать приложения, которые анализируют Doc-блоки и составляют сопроводительную документацию к приложению, основываясь на его содержимом.

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

В результате код не будет чрезмерно сложным:

<?php
    class Deposit {

        /**
         * @var string
         */
        private $_owner;

         /**
         * @var float
         */
        private $_amount;

        /**
         * @var DateTime
         */
        private $_dateOpened;

        //...

        /**
         * @param string $owner
         */
        public function setOwner($owner) {
            $this->_owner = $owner;
        }
?>

Заключение

В этой статье я дал вам несколько советов насчет того, как обеспечить документирование кода в PHP-приложениях. Я думаю, комментарии не нужны, если вы создаете код, который понятен и объясняет сам себя.

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

Также не стоит забывать вставлять теги Doc-блоков, которые описывают типы переменных или возвращаемые значения функций, поскольку такая информация не может быть включена в сам код.

Если вам нужно предоставить более детальную документацию по проекту, я также рекомендую помещать соответствующие описания в Doc-блоки.

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