Очень много времени в разработке отводится написанию кода. Над кодом работают разные люди, часто несколько “поколений” программистов меняются в течении жизненного цикла одного проекта. Поэтому вопрос относительно комментариев возникает достаточно часто. Стоит ли их писать? Когда и кто должен их писать? Я решил написать о моем личном подходе к комментариям.

Начнем с самого определения к комментариям. Для меня они образно делятся на два типа: документация публичного API и все остальные комментарии. С публичным API все просто – без комментариев в нем зачастую просто никак. Связано это в первую очередь с тем, что для публичного API не всегда доступны исходники, но при этом нужно предоставить информацию пользователям о правилах использования. Как бы классно вы не называли интерфейсы, классы, методы и параметры, это не даст представления об общей логике использования API, частных случаях и особенностях применения. Могли бы помочь модульные и интеграционные тесты, но они не всегда включаются в поставку или отсутствуют. Да и представьте себе насколько возрастут усилия по применению API, если вам нужно будет постоянно разбираться с чужими тестами. В итоге мой вердикт таков – если у вас есть API, который для кого-то является публичным, то вы просто обязаны снабдить его документацией в виде комментариев. Чтобы эти комментарии не устаревали и не теряли своей актуальности, внесите пункт об их обновлении в критерии готовности кода.

Теперь перейдем ко всем остальным комментариям. С моей точки зрения они абсолютно бесполезны и позволяют разработчикам “дать слабину”. Написали вы сложный и запутанный кусок кода, который понятен только вам, и думаете что же делать. И тут приходит решение – добавил комментарий и готово. Просто и быстро. Реализовали вы “hack” вместо нормального решения и написали рядом: “Лучше не трогайте этот код, если дорожите своим местом работы”. И вроде все хорошо. Если у вас есть время и желание посмеяться, то я настоятельно рекомендую почитать примеры такого рода комментариев. Отлично проведете время! Но давайте задумаемся для чего мы пишем комментарии? В основном для того, чтобы сообщить следующему разработчику некую важную информацию. Для этого мы выбираем текстовый формат комментария, который будет жить параллельно с самим кодом. Именно это и является причиной всех бед с комментариями: устаревание, неактуальность, бесполезность и так далее. Вместо этого нужно искать лучший способ передачи информации.

Таким способом является использование самого кода. Ведь нам доступно множество способов сохранить информацию для следующего разработчика: имя класса, имя метода, имя переменной, имя параметра и многие другие элементы кода. Не стоит экономить на длине имен, современные средства разработки очень хорошо визуализируют программный код. Я приведу небольшой пример из недавней практики. При сохранении сущности в базу данных в той же транзакции сохраняются ее дочерние сущности, которые в свою очередь являются связками к существующим сущностям (отношения многие ко многим). К сожалению, в реализации MySql вставка блокирует внешний ключ на таблицу, что легко приводит к дедлоку (deadlock) при одновременной вставке нескольких сущностей с одинаковыми дочерними. Помогает в данной проблеме сортировка дочерних сущностей по первичному ключу, чтобы блокировки захватывались в одинаковом порядке. В код перед сохранением была добавлена сортировка, которая с виду казалась абсолютно бесполезной. Думаю, очень скоро ее бы запросто удалили при рефакторинге кода. Первая мысль, которая возникла у многих – нужно добавить комментарий с описанием причины происходящего. Вместо этого сортировка была вынесена в отдельный метод с названием orderXXXToPreventDeadlock, название которого содержала точно такую же информацию как и комментарий, но при этом оставаясь частью самого кода. Дополнительный плюс указанного решения в том, что этот метод по сортировке стал хорошим кандидатом на повторное использование в других местах с подобной проблемой.

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

Каково ваше отношение к комментариям в коде? В каких случаях вы не могли обойтись без них?