Немного о видах комментариев в коде

Рубрика: Development | 31 October 2007, 10:32 | Vadim Voituk

Я разработчик с 7летним стажем.
5 из них – это профессиональная деятельность.
И я утверждаю, что почти не пишу комментарии в коде.

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

Немного поясню свою позицию.
Давайте определимся какие бывают типы комментариев в коде:

1. Комментарии в Doc-блоке – это тип комментариев предназначенный для последующей обработки специальной утилитой (JavaDoc, PHPDoc, GroovyDoc) и совместно с синтаксическим анализом кода позволяют формировать девелоперскую документацию. В Си-подобных языках обычно заключаются в блок /** */
Такие комментарии писать нужно и даже иногда полезно. Единственное чего не стоит писать в Doc-блоке, так это деталей реализации структурного элемента (класса, метода, etc).
С другой стороны при постоянном рефакторинге кода актуальность этих комментариев оставляет желать лучшего.
Хорошо, конечно, что большинство современных IDE сами отрефакторят Doc-блок согласно изменениям параметров и типов, но все-таки обновление комментариев чаще всего ложится на плечи разработчика, а это уже затраты дорогостоящего времени.
Мой мнение в этом вопросе: Doc-блок писать нужно хотя бы согласно CodeConventions и ради JavaDoc/PHPDoc/etc документации, но при этом сигнатура описываемого метода или класса должна быть понятна без Doc-блока.
Добиться этого можно путем присвоения читаемых и понятных имен классам/методам/полям/параметрам.

2. Комментарии, описывающие ЧТО и КАК делает код.
Такие комментарии часто встречаются внутри кода, и являются по сути самыми опасными комментариями.
Опасными потому, что во-первых при замещении/подстановке алгоритма эти комментарии обновляются редко. В лучшем случае разработчик просто их удалит как неактуальные. Во-вторых такие “пояснения” к коду – это душок плохого/непонятного кода, над которым нужно проводить рефакторинг.
Почему не стоит писать такие комментарии очень доступно написано в первой главе книги Martin Fowler “Refactoring”.

3. Структурные комментарии используются для отделения одного блока кода от другого.
Приведу пример:
[java]

// Try to login user
bool logged = User.login(login, password);
...

if (logged){
  // Do smth with logged user
  ...
  ...
} else {
  // Display auth error
  ...
  ...
}

[/java]
Даже на таком утрированном примере видно, что особой смысловой нагрузки такие комментарии не несут, т.к. все понятно и без них. Их цель немного другая – отделить структурные части большого куска кода один от другого, дабы упростить чтение и навигацию по этому коду.
Часто среди unix-пользователей для таких комментариев используют специальные маркеры, по которым редактор (vim или emacs) проводит сворачивание кода (folding).
Например:
[java]

// Try to login user
bool logged = User.login(login, password);
...

if (logged){
  // {{{ Do smth with logged user
  ...
  ...
  // }}}
} else {
  // --- Display auth error -------------
}

[/java]
Лично я более чем уверен что такие комментарии самые полезные и писать их нужно обязательно.

Возможно деление комментариев всего на 3 класса – это примитивно, но очень надеюсь, что мне удалось донести до читателя понимание того, что “комментарии-комментариям рознь”, и не стоит слепо верить в постулат “комментарии писать нужно”.

Комментариев: 9

9 Responses to “Немного о видах комментариев в коде”

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

  1. Andy

    Бывают еще и комментарии ЗАЧЕМ и ПОЧЕМУ код написан именно таким образом… Вот они как раз и пишутся чаще всего. А если не пишутся, когда надо, то лентяев нагибают и они все равно пишутся…

  2. Скакунов Александр

    А я пишу комменты для себя.

  3. vadim

    ЗАЧЕМ и ПОЧЕМУ

    Это как раз те комментарии, от каких стоит избавляться. Хотя действительно – такие существуют и порой приносят пользу.

  4. Chabster

    Вайт, почитай Макконелла. Для начала.
    А второе – попробуй использовать незнакомое АПИ без документации. Я, естественно, опять клоню к миллионам строк распределенного кода. Но ты попробуй просто апи без жавадок.

  5. vadim

    Chabster, не перекручивай!
    Где в статье написано “без жавадок”? А где написано “без документации”?

    Кстати настоящие TDD-шники комментарии не пишут в принципе :)
    А твои “миллионы строк распределенного кода” – это частный случай, для которых каждая строка комментария на вес золота.
    Это же касается legacy-кода.

  6. Chabster

    Жавадок – для кода, который заведомо корректный и изменению не подлежит (как правило – API).
    Весь остальной код должен принудительно комментироваться. За отсутствие каментов в больших методах со сложными вычислениями я бы открутил башку.
    “настоящие TDD-шники комментарии не пишут в принципе” и, видимо, пишут в одиночку или с соседом по унитазу…

  7. vadim

    За отсутствие каментов в больших методах со сложными вычислениями я бы открутил башку

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

    Про TDD почитай у Бэка, много нового узнаешь. Для начала :)

  8. Chabster

    А можно не рефакторить, а написать нормальные коментарии. Цель одна и та же – представить код на более абстрактно-понятном уровне.

    Кент пишет полную чушь. А следуют его бредовым принципам исключительно из-за популярности автора. И ХР – полная х***я. А книга его про TDD – редкостный отстой. Хуже не видел.

  9. vadim

    Оно и видно что не видел :)

Leave a Reply