Taras_Serevann
@Taras_Serevann
веб-разработчик, автор

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

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

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

Построчный, с последовательным объяснением всех действий
9e8e9d4729994892a9fe4c241bb7150a.png
И более строгий, в котором сначала объяснение а потом действие.
0835300d51fb4654a47c9b6ae1acb425.png
Какой из этих стилей лучше и правильнее? И почему? Возможно, есть какие-то официальные рекомендации?
  • Вопрос задан
  • 1056 просмотров
Решения вопроса 6
saboteur_kiev
@saboteur_kiev Куратор тега Программирование
software engineer
Пишите комментарии на английском. Это упростит поддержку проекта в будущем, включая поддержку нерусскоязычными программерами.

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

Комментировать нужно метод или класс целиком, общими словами. Отдельные строчки комментируются в качестве исключения, либо в случае каких-либо изменений, типа
// special exception, see issue #123191239
Ответ написан
trevoga_su
@trevoga_su
за советы не писать комментарии я считаю нужно больно бить и пожизнено лишать возможности работать программистом.
код комментариями не испортить, а вот те, кто придут после вас (или вы сами через месяц, полгода, 10 лет) - будут вам очень благодарны.
самодокументируемый код - это миф.
все любят ссылаться на фреймворки, но почему-то многие забывают, как дотошно комментируют код во всех современных фреймворках.
Ответ написан
@Silm
https://ru.wikipedia.org/wiki/PHPDoc

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

И да, вы забыли, что блочный комментарий выгладит так /* */
Ответ написан
Fesor
@Fesor
Full-stack developer (Symfony, Angular)
с последовательным объяснением всех действий


Пишите код так, что бы не нужно было комменты делать для действий, только для отдельных методов. Если вот совсем никак и надо объяснить что делает блок кода - выносим его в приватный метод с адекватным названием. Вот и все.
Ответ написан
@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);
    }
Ответ написан
@abcd0x00
Лучшие из всех те комментарии, которые не нужны. А вообще, да, пиши комментарии на каждый чих, чтобы научиться просто их писать и знать, что в них писать надо, а что не надо. И тогда ты сможешь прийти к тому уровню, когда у тебя сам код станет комментарием самого себя.
Ответ написан
Комментировать
Пригласить эксперта
Ответы на вопрос 3
@dmitryKovalskiy
программист средней руки
Оба способа - хрень. Код пишите красивый и самодокументируемый. Используйте вменяемый метод именования.
А за такие простыни комментариев следует наказывать
Ответ написан
@res2001
Developer, ex-admin
Вообще код сам себя комментирует для человека его понимающего. А другим и комментарии не помогут.
Комментарии требуются только в "тонких", не очевидных моментах.
Для большей удобочитаемости давайте переменным и процедурам понятные имена.
Ответ написан
@kalyabus
Про кривые ручки, костыльки и прочую ересь забудьте в комментарии, они должны быть более официозными. Ну и каждую строчку комментировать - явно излишне, это все равно что говорить в слух "А вот щас я сделаю шаг, за ним еще шаг, потом третий и я дойду до холодильника, но если на третьем шаге у меня окажется кошка, то я споткнусь об нее"
Ответ написан
Комментировать
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы