Pull to refresh

Комментарии в коде — полезные, бессмысленные, вредные?

Reading time 3 min
Views 27K
Как-то проглядывая код некоторых старых модулей, вновь подумал о роли комментариев. Вопрос хоть и тривиальный и обсужденный миллионы раз в книгах, блогах, статьях и форумах, а все-таки подчас задевает за живое. При этом, о пользе комментариев пишут гораздо чаще, чем о их вреде.

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

Итак:


1. Комментарий может быть полезным, бессмысленным или вредным.
2. Если комментарий не несет явно видимой пользы, то он скорее всего вреден.
3. Комментарии бесполезны / вредны чаще, чем кажется. Отсутствие комментария лучше, чем бесполезный комментарий.
4. Перед тем, как написать комментарий — подумайте дважды, а может не стоит? :)
(5. После того, как вы решили, что комментарий все-таки не нужен, посмотрите трижды — а код точно кристалльно понятен?:))


Про полезные комментарии все ясно. Когда:
— достаточно прочитать 6 строк комментария вместо 80 строк кода метода с бизнес-логикой
— в комментарии дается ссылка на реализуемый малоизвестный алгоритм или структуру данных (например — «для поиска подстроки используется алгоритм Ахо — Корасик», ссылка на википедию или спец. сайт)
— комментарий поясняет, почему автор использует не тот подход, который читающий код скорее всего ожидает тут увидеть (например, написанный руками SQL запрос вместо работы через ORM фреймворк, или почему для поиска в XML используется regexp, а не XPath)
— в комментарии дан короткий ясный пример использования (особенно, если это какой-нибудь custom Ant task или что-то подобное),

то это почти наверняка полезный, а подчас необходимый комментарий.

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

  1. /**
  2. * return the enterpriseName
  3. */
  4. public String getEnterpriseName() {
  5. return enterpriseName;
  6. }


Комментарий, очевидно, не нужен. Ничего нетривиального в коде нет, комментарий по сути дублирует код. Кроме того — комментарий здесь занимает три строки в редакторе кода. Т.е. ровно столько же, сколько и сам код. Мало того что сам код, по сути, синтетический, + из-за Java Code Conventions растягивается три строчки ради удобочитаемости, так еще и комментарий отъедает место.
Java и так маловыразительный язык (с точки зрения среднего количества полезных действия на строку кода) по сравнению с, например, Ruby или Groovy, так зачем тратить экранное место под лишние комментарии.

Тут, конечно, есть тонкий момент. Если код с подобными комментариями — это часть public API какой нибудь generic библиотеки, и никто из пользующихся ей программистов почти никогда не смотрит ее исходники, а смотрит Javadoc — тогда это еще нормально. Но если этот код находится в каком нибудь модуле, разработываемом нами, и исходники этого класса смотрят чаще, чем документацию к нему (что почти всегда верно) — тогда это ИМХО, тот случай, когда правило «любой элемент API должен иметь комментарий» должно применяться с большой осторожностью.

Рассмотренный пример часто дополнительно ухудшается тем, что в комментарий запихиваются теги param, return, которые часто полезной информации не несут, а вот место съедают. Например:

/**
*
* Some description.
* param paramName1 paramName1
* param paramName2 paramName2
* param paramName3 paramName3
* return the name of user
*/
public String getUserName(String paramName1, int paramName2, int paramName2) {
/* какой то простой прямолинейный код*/
}

(Забавно, что часто в коде есть такие бессмысленные комментарии, а в реально сложных частях комментариев мало :))

И напоследок еще пример.

// Временный хак, т.к. возможность сделать нормально сейчас не поддерживается,
// а сделать надо срочно. По совету [senior developer name], хакнул так.
// 21/04/2004, [developer name].

В некоторых примерах я частично утрирую, но общая идея от этого не меняется.

Updated:
По просьбам в комментах, даю ссылку на пару книг, которые полезно прочитать любому программисту, чтобы не писать таких комментариев (и не делать многих других ошибок)

Стив МакКоннелл. Совершенный код. www.ozon.ru/context/detail/id/5508646
Мартин Фаулер. Рефакторинг. Улучшение существующего кода. www.ozon.ru/context/detail/id/4952415
Tags:
Hubs:
+35
Comments 221
Comments Comments 221

Articles