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

Я разработчик с 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 класса – это примитивно, но очень надеюсь, что мне удалось донести до читателя понимание того, что “комментарии-комментариям рознь”, и не стоит слепо верить в постулат “комментарии писать нужно”.