<rmcreative>

RSS

Когда стоит писать комментарии в коде

10 января 2015

Бытует мнение, что писать комментарии к коду не нужно. Пошло оно, скорее всего, от высказывания одного из отцов программирования — Брайана Кернигана: «Don’t comment bad code, rewrite it». Как всегда, находятся фанатики, которые странно воспринимают авторитетные высказывания и никогда не пишут комментарии принципиально. Это неправильно.

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

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

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

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

Комментарии RSS

  1. №9551
    klay
    klay 10 янв. 2015 г., 19:52:21

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

  2. №9552
    Sam
    Sam 10 янв. 2015 г., 19:56:48

    Код методов не нуждается в комментариях, а вот документировать методы всё-таки надо...

  3. №9553
    mktums
    mktums 11 янв. 2015 г., 7:04:58

    @klay ты еще мои однострочники не видел ;)

  4. №9556
    Alexey
    Alexey 12 янв. 2015 г., 11:01:43

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

  5. №9560
    Костя
    Костя 13 янв. 2015 г., 9:21:32

    @Alexey, да враки это все. За комментариями к методу также стоит следить как и за самим кодом. Написал php-doc сгенерь документацию и посмотри результат. Намного проще за комментариями следить, если проект на симфони или это джава спринг, там аннотации рекомендуется юзать, сразу будешь обращать внимание на комментарии и важность. И не должна лень перебаривать желание написать  комментарий к методу. А то получается, что это из разряда — в документации не напишу пример, если хотите пример, откройте тесты и посмотрите скрипт тестирования. Бред же ж.

    @klay, ага, однострочники, то-то в капистрано магия какая-то :D

  6. №9564
    Alexey
    Alexey 13 янв. 2015 г., 14:06:05

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

  7. №9565
    Костя
    Костя 13 янв. 2015 г., 14:15:03

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

  8. №9566
    Костя
    Костя 13 янв. 2015 г., 14:18:30

    Ох, что-то я с ошибками пишу) В общем я тимлидил и есть опыт выстраивания гайдов по проекту :)

  9. №9567
    Роман
    Роман 13 янв. 2015 г., 14:59:08

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

    От одной крайности в другую не уходите. Слишком мягкие правила == отсутствие правил. Не бывает самодокументируемого кода в больших системах в «реальной жизни». Просто потому, что а) публичный API состоит из большого числа методов б) работать приходится с более чем одним API одновременно.

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

  10. №9568
    Alexey
    Alexey 13 янв. 2015 г., 15:02:48

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

  1. Почта опубликована не будет.

  2. Можно использовать синтаксис Markdown или HTML.

  3. Введите ответ в поле. Щёлкните, чтобы получить другую задачу.