PHP: комментирующий код

Question

Добрый день всем,

Получил теоретический вопрос.

Я создаю простое приложение с использованием фреймворка KohanaPHP. Это мой первый раз с фреймворком, и у меня один, может быть, глупый вопрос для некоторых из вас

При разработке классов или функций я комментирую свой код с помощью DocBlock. Просто интересно, как мне комментировать мой код при использовании фреймворка? Я хотел закодировать некоторые части кода, а не целые контроллеры.

В основном я использую следующие методы:

// Check if variable_name is greater than zero
if($this->var > 0) {
    // do something
} else {
    // do something
}

if( $result ) {
    // display confirmation message
} else {
    // display errors
}

Я делаю это правильно? Есть ли какой-нибудь стандарт для вставки комментариев в код?

Edit: Позвольте мне объяснить, я не использую комментарии типа «проверить, если переменная больше нуля». Мне просто интересно, если это хорошая практика, чтобы оставлять комментарии в коде.

С уважением, Том

Answer 1

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

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

Answer 2

Лично я экономно документирую inline (хотя я неукоснительно вставляю doc-блоки для методов, классов и переменных-членов).Я считаю, что сам код должен быть как можно более самодокументированным.

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

В классе CodeCoverageReportTask Phing есть отличный пример:

// Strange PHP5 reflection bug, 
//     classes without parent class or implemented interfaces 
//     seem to start one line off
if ($reflection->getParentClass() == NULL 
    && count($reflection->getInterfaces()) == 0)
{
    unset($coverageInformation[$classStartLine + 1]);
}
else
{
    unset($coverageInformation[$classStartLine]);
}

И еще один хороший пример всего лишь на несколько строк ниже:

// PHP5 reflection considers methods of a parent class to be part 
//     of a subclass, we don't
if ($method->getDeclaringClass()->getName() != $reflection->getName())
{
    continue;
}

Answer 3

// Check if variable_name is greater than zero

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

Как общее (не зависящее от языка) практическое правило, пишите код, который в основном самодокументируется (используя описательные имена, избегая неочевидных ярлыков и т. Д.), И комментируйте только то, почему вы делаете что-то, что выглядит неправильно / странно. *

Answer 4

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

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

Answer 5

Комментарии - это лжецы! Проблема с комментариями заключается в том, что вы должны обновлять их при обновлении кода.Если вы этого не сделаете, вы получите код, похожий на этот:

// sum $a and $b
$x = $a * $a - $b;

Так что лучший способ документировать ваш код - сделать его действительно понятным!Я написал бы ваш код так:

if ( isPositive(3) ) {
    doA();
} else {
    doB();
}

if( $result ) {
    displayConfirmationMsg();
} else {
    displayErrors();
}

Этот код вообще не нуждается в комментариях, потому что его очень просто понять!

Ну, во всяком случае, когда мне приходится писатькомментарии (почти никогда), я иду с примечанием //, но я думаю, что это не имеет значения.

Кстати, посмотрите это потрясающее видео дяди Боба http://bit.ly/AYqFT

Answer 6

Некоторые (если не большинство) PHP-программисты используют метод двойной косой черты (//) для комментирования своего кода. Там действительно нет стандарта, я видел людей, которые комментируют, используя символ фунта (#) в начале строки, и других, которые комментируют блоки с /* и */.