fbpx
Стоит ли писать комментарии к коду?

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

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

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

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

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

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

Обсуждение (
Warning: A non-numeric value encountered in /sata1/home/users/xpinjecti/www/www.xpinjection.com/wp-includes/pomo/plural-forms.php on line 280

Warning: A non-numeric value encountered in /sata1/home/users/xpinjecti/www/www.xpinjection.com/wp-includes/pomo/plural-forms.php on line 280

Warning: A non-numeric value encountered in /sata1/home/users/xpinjecti/www/www.xpinjection.com/wp-includes/pomo/plural-forms.php on line 280

Warning: A non-numeric value encountered in /sata1/home/users/xpinjecti/www/www.xpinjection.com/wp-includes/pomo/plural-forms.php on line 280

Warning: A non-numeric value encountered in /sata1/home/users/xpinjecti/www/www.xpinjection.com/wp-includes/pomo/plural-forms.php on line 280

Warning: A non-numeric value encountered in /sata1/home/users/xpinjecti/www/www.xpinjection.com/wp-includes/pomo/plural-forms.php on line 280
4)

Как писал дядюшка Боб в “Чистом коде”: Лучший комментарий тот, которого удалось избежать.

Совершенно не нова. Я хотел больше отметить даже не то, что можно улучшить код, а что можно информацию из комментария просто отобразить в другом виде. Спасибо за цитату. 🙂

На самом деле идея не нова:

Good code is its own best documentation. As you’re about to add a comment, ask yourself, “How can I improve the code so that this comment isn’t needed?”
— Steve McConnell

🙂

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Мы используем файлы cookies для различных целей, включая аналитику и персонализированный маркетинг. Продолжая пользоваться сайтом, вы соглашаетесь на использование файлов cookies. Подробно ознакомиться с правилами работы с файлами cookies можно здесь

принять
Pkv Games BandarQQ Online Terbaik Dengan Deposit Super Modern permainan paling populer di situs poker online terbaik di indonesia di situs bukaqq Poker Online Aman dan Terpercaya slot online