Какой стиль комментирования кода правильнее?

Question

[Тарас Сереванн]

В PSR и в интернете по этой теме вроде бы ничего нет.

Есть два стиля комментирования кода:

Построчный, с последовательным объяснением всех действий

И более строгий, в котором сначала объяснение а потом действие.

Какой из этих стилей лучше и правильнее? И почему? Возможно, есть какие-то официальные рекомендации?

Comments

[Алек Оним]

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

[Николай Романович]

ИМХО, второй вариент выглядит более приемлимо, глаза не разбегаются. Да и вообще, не стоит так подробно все комментировать, "переписывать алгоритм словами".

Answer 1

[Saboteur]

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

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

Комментировать нужно метод или класс целиком, общими словами. Отдельные строчки комментируются в качестве исключения, либо в случае каких-либо изменений, типа
// special exception, see issue #123191239

Comments

[trevoga_su]

> Пишите комментарии на английском.

почему не на индусском или на японском?

[Saboteur]

trevoga_su: Потому что в программировании английский распространен больше.
Потому что с английской кодировкой нет проблем нигде.
Потому что это гораздо более международный язык, чем индусский или японский.
Глупый вопрос.

[trevoga_su]

Сергей: это не аргумент
если проект не делается для "западного партнера" (с), то нет никаких доводов писать комментарии на иностранном языке

[Saboteur]

trevoga_su: В таком случае, почитайте внимательнее мой ответ целиком.

[trevoga_su]

Сергей: за английские комментарии в руSSком быдлокоде я бы убивал жестоко, медленно, как Чикатилло

[Saboteur]

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

Answer 2

[trevoga_su]

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

Comments

[Тарас Сереванн]

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

[Дмитрий Ковальский]

Напишите 2 строчки комментариев на 1 строчку вашего кода и мы узнаем можно его испортить или нет.

[Silm]

Тарас Сервеванн: trevoga_su: Фреймворки документируют комментариями, а не описывают происходящее. Это совершено не то, что демонстрирует автор в своем примере. Сравните сами...

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

[trevoga_su]

> Сравните сами...

ну да, у автора немного треш..

Answer 3

[Silm]

https://ru.wikipedia.org/wiki/PHPDoc

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

И да, вы забыли, что блочный комментарий выгладит так /* */

Comments

[Тарас Сереванн]

Думаю, у меня он как раз скорее для документации применяется

[Silm]

Тарас Сервеванн: в вашем примере совершенно нет. В вашем примере комментарии описывают что делает код. А если бы они были документацией они бы описывали как работать с этой функцией/методом/классом.

Документирующий комментарий должен выглядеть так: "Функция приминает на вход дату, возвращает день недели". А что происходит внутри должно быть строго неизвестно.

[Тарас Сереванн]

Silm: понятно, спасибо

Answer 4

[Сергей Протько]

с последовательным объяснением всех действий

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

Comments

[Тарас Сереванн]

Как бы вы переделали код на картинке?

[Сергей Протько]

Тарас Сервеванн: Я бы в принципе по другому пути шел. Но если именно ваш код

public function handle($postId=null, $text=null) {
    if ($postId) {
        return $this->handleByPostID($postId);
    }

    return handleByText($text);
}

private function handleByPostID(int $postId) {
    if ($this->hasCustomTime($postId)) {
         return $this->getCustomTimeByID($postId);
    }

    return $this->handleByText(
        $this->getPostTextById($postId)
    );
}

private function handleByText(string $text) {
    return $this->getTimeRead($text);
}

[Тарас Сереванн]

Сергей Протько: спасибо. А исключение где здесь лучше всего выбросить?

[Тарас Сереванн]

Сергей Протько: и в принципе по другому пути это по какому?

[Сергей Протько]

Тарас Сервеванн: я бы бросал его где-то раньше, при проверке запроса. Ну и сам по себе метод handle какой-то отстой.

Мне не нравится метод вида getCustomTimeByID($postID). я бы пост по ID получил и запросил бы у него это время, а как оно там внутри мне неважно. Инкапсуляция же. А тут - процедурщина под соусом из классов.

Answer 5

[dev400]

/**
     * Return link to PDO connection on system database
     * @return \PDO
     */
    public function con() {
        $this->count++;
        return $this->link;
    }

    /**
     * Return query count maked to database. Function for debug.
     * @return int
     */
    public function getQueryCount() {
        return $this->count;
    }


    /**
     * Check is database down now
     * @return bool
     */
    public function isDown() {
        return is_null($this->link);
    }

Comments

[Тарас Сереванн]

Как бы вы переделали мой код?

[dev400]

Тарас Сервеванн: Посмотрите популярные фреймворки, как там комментируют. И переделайте сами.

Answer 6

[abcd0x00]

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

Answer 7

[Дмитрий Ковальский]

Оба способа - хрень. Код пишите красивый и самодокументируемый. Используйте вменяемый метод именования.
А за такие простыни комментариев следует наказывать

Comments

[trevoga_su]

красивый и самодокументируемый код - это миф

[Тарас Сереванн]

Что не так с именованием в коде на картинке?

[Дмитрий Ковальский]

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

//Если объект не равен null
if(obj!=null)

И встает вопрос - а нафига тогда комментарий? Для человека, не способного понимать по английски?
Такие комментарии увеличивают размер метода и затрудняют чтение - приходится разделять код и комментарии на глаз. Я понимаю если у вас написано if(a<3) - тут требуются пояснения, но и именование гавёное.

[Дмитрий Ковальский]

trevoga_su: Зато свалка комментариев - суровая реальность

Answer 8

[res2001]

Вообще код сам себя комментирует для человека его понимающего. А другим и комментарии не помогут.
Комментарии требуются только в "тонких", не очевидных моментах.
Для большей удобочитаемости давайте переменным и процедурам понятные имена.

Comments

[Тарас Сереванн]

По практике, прочитать комментарии проще и быстрее, чем вникать в код.

[Silm]

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

[abcd0x00]

Тарас Сервеванн:

По практике, прочитать комментарии проще и быстрее, чем вникать в код.

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

Answer 9

[kalyabus]

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